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Preface 


I  became  intrigued  with  reed  time  systems  in  the  f^pring  of  11W6.  Here  was  an 
application  domain  where  using  formal  methods  is  justified,  because  the  cost 
in  life  and  property  of  programmer  errors  could  be  so  great.  Here  also  was  an 
application  domain  where  making  assumptions  about  hardware  failure  modes 
is  inappropriate,  and  so  a  system  must  be  able  to  tolerate  so-called  Byzantine 
failures.  My  research  efforts  had  been  concerned  with  these  two  subjects,  thus 
putting  me  in  the  enviable  position  of  having  discovered  a  "problem"  for  my 
various  “solutions". 

Attacking  a  real  process-control  problem  seemed  like  a  good  way  to  get  a 
better  understanding  of  the  area.  But,  which  problem?  The  problem  had  to 
be  simple  enough  so  that  Computer  Science  issues  dominated  any  application- 
dependent  details.  Yet,  the  problem  could  not  be  too  simple  or  else  some  key 
cispect  of  real-time  systems  might  be  overlooked.  1  was  aware  that  various 
research  groups  (e.g.,  at  University  of  Newcastle  upon  Tyne  and  at  University 
of  Waterloo)  had  used  electric  toy  trains  as  a  vehicle  [sic]  for  such  research, 
and  so  that  was  an  obvious  place  to  start.  After  studying  a  bit  of  railroading, 
however,  it  became  clear  that  toy  trains  are  not  accurate  models  of  reality  — 
they  change  the  problem  too  much.  For  example,  real  trains  cannot  accelerate 
or  decelerate  as  rapidly  as  toy  trains  do.  Therefore,  a  control  program  for 
a  real  train  must  anticipate  changes  to  train  speed;  a  control  program  for  a 
toy  train  need  not.  Some  of  the  inaccuracies  of  toy  trains  can  be  corrected 
by  modifying  the  electronics  used  to  control  the  trains,  but  dealing  with  this 
and  the  other  custom  hardware  necessary  for  integrating  a  toy  train  set  with 
a  computer  system  seemed  like  a  black  hole  (as  only  custom  hardware  can  be) 
that  I  should  avoid.  Thus,  I  decided  to  build  a  railroad  simulator  along  with 
support  software  for  constructing  railroad  layouts,  controlling  those  layouts  from 
networks  of  computers,  and  monitoring  such  control  experiments. 

After  the  first  version  of  the  railroad  simulator  was  built,  it  became  clear 
that  my  circumstances  were  not  unique.  Other  scientists  were  also  becoming 
interested  in  studying  real-time  programming  issues  and  they,  too,  felt  that  a 
prototype  application  could  be  a  useful  research  tool.  Courses  on  real-time  sys¬ 
tems  would  benefit  from  using  this  software  in  laboratory  exercises,  particularly 
because  specialized  hardware  and  software  were  not  required.  So.  we  cleaned- 
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up  the  code,  wrote  some  user  documentation,  and  put  together  this  software 
distribution. 

The  Trainset  system,  as  our  railroad  simulation  software  is  now  known, 
is  the  work  of  many  people  over  the  last  a  years.  Jacob  .4izikowitz  defined 
our  model  of  railroads  and  wrote  the  first  railroad  simulator  in  the  spring  of 
1987;  it  ran  under  SUNOS  Unix.  Jacob  also  supervised  MEng.  students  Ellen 
Blood,  Anthony  Pellegrini,  and  Jane  Smidesang  in  producing  an  XIO  graph¬ 
ics  interface  to  the  system.  Michael  Abbott,  an  undergraduate,  then  defined 
and  implemented  a  high-level  interface  to  the  simulator  for  use  by  control  pro¬ 
grams.  This  software  was  then  rewritten  and  ported  to  VMS,  ULTRIX.  and 
XI  1/DECWindows  Tony  Lekas,  a  DEC  engineer  working  with  us  as  part  of 
a  DEC-funded  research  project  at  Cornell.  Dick  Brown  joined  the  project  in 
Fall  1989,  spending  that  year  and  the  following  spring  term  on  a  major  rew'rite 
of  the  system  and  writing  documentation  for  what  we  had.  Dick  was  assisted 
by  Thomas  Bressoud,  who  rewrote  and  documented  the  layout  editor  and  part 
of  the  graphics  monitor  software.  Most  recently.  Donald  VVihardja  has  helped 
us  debug  the  installation  procedure. 

This  software  development  effort  would  not  have  been  possible  without  fi¬ 
nancial  support  from  a  number  of  sources.  My  research  in  concurrent  and 
distributed  systems  has  been  funded  by  grants  from  the  National  Science  Foun¬ 
dation  since  1978  and  from  the  Office  of  Naval  Research  since  1985.  Dr,  Andre 
van  Tilborg,  now  the  division  director  for  Computer  Science  at  ONR,  was  es¬ 
pecially  supportive  as  my  ONR  program  manager  during  the  initial  stages  of 
this  project,  amd  Gary  Koob,  his  successor,  has  continued  that  tradition.  Fund¬ 
ing  from  Digital  Ekjuipment  Corporation  was  also  critical  to  the  success  of  this 
project.  Ed  Balkovich  of  DEC  encouraged  me  to  apply  for  funding  under  Digi¬ 
tal’s  External  Research  Program  (ERP)  and  then  served  as  our  corporate  liaison, 
helping  to  transfer  our  research  results  to  engineers  at  DEC  who  could  benefit 
from  them.  The  DEC  ERP  funds  allowed  us  to  procure  hardware  for  the  labo¬ 
ratory  used  to  develop  this  software  and  to  run  real-time  systems  experiments. 
John  Gannon,  the  Software  Engineering  Program  manager  at  NSF  for  1988-89, 
tilerted  me  to  the  NSF  Software  Capitalization  Initiative  and  encouraged  me  to 
apply.  Funding  from  that  program  supported  Dick  Brown’s  stay  at  Cornell  and 
is  largely  responsible  for  transforming  our  research  prototype  into  a  system  that 
could  be  widely  distributed. 


Fred  B.  Schneider 
Ithaca,  New  York 


Chapter  0 


Introduction  and  Overview 


Trainset  is  a  real-time  simulation  of  a  railroad.  The  software  consists  of  a  sim¬ 
ulator,  an  interactive  graphics  editor  for  defining  railroad  layouts  and  graphics 
monitor  programs  for  displaying  the  state  of  the  railroad  and  manually  control¬ 
ling  it.  Two  communications  interfaces  to  the  simulator  are  provided. 

•  The  control  program  interface  (CPI)  is  used  by  computer  programs  that 
control  Trainset  railroads.  The  CPI  consists  of  library  routines  and  data 
strucluies,  collectively  called  the  ACl  (Automatic  Control  Interface),  and 
low-level  message  formats  and  related  facilities,  called  the  LLI  (Low-Level 
Interface). 

•  The  monitor  interface  is  used  only  by  the  graphics  monitor  programs. 

These  interfaces  can  be  in  use  simultaneously. 

Trainset  has  been  implemented  in  C  language  on  Digital  Equipment  Corp. 
Ultrix,  using  DECwindows/X-ll  and  TCP/IP  or  DECnet. 

This  manual  introduces  Trainset  and  gives  specifications  for  the  railroads  it 
implements.  The  document  also  discusses  the  mechanics  of  using  Trainset  and 
provides  other  information  that  a  researcher  or  student  should  know  in  order  to 
write  control  programs  that  interact  with  Trainset  railroad  layouts. 

The  manual  is  organized  as  follows. 

Chapter  1  is  a  tutorial  on  using  the  .softw'are.  It  includes  instructions  for 
running  a  demonstration,  creating  and  simulating  a  railroad  layout  and  writing 
programs  to  control  a  Trainset  railroad,  A  simple  programming  example  is 
discussed  to  illustrate  the  use  of  the  ACl. 

Chapter  2  specifies  the  attributes  of  simulated  railroads  that  Trainset  sup¬ 
ports. 

Chapter  3  discusses  the  ACl.  A  high-level  mechanism  is  presented  for  estab¬ 
lishing  a  connection  with  a  running  Trainset  railroad  simulation  and  receiving 
an  initial-state  download  of  that  railroad.  Commands  and  queries  are  described 
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for  interacting  with  a  Trainset  railroad.  I  tilily  routines  that  provide  timer 
facilities  are  introduced,  and  a  service  is  discussed  that  supports  the  writing  of 
fault-tolerant  control  programs. 

Chapter  4  documents  the  LLl.  This  information  will  be  of  interest  to  pro¬ 
grammers  who  wish  to  bypass  the  ACI  layer  or  reimplement  it  for  other  envi¬ 
ronments. 

The  appendices  include  reference  pages  for  the  programs  that  comprise 
Trainset  and  selected  code  listings. 

A  separate  installation  guide  accompanies  the  software  distribution. 


Obtaining  a  Copy 

You  may  obtain  a  copy  of  the  Trainset  software,  installation  instructions  and 
the  text  of  this  manual  from  either  of  the  Internet  sites  listed  below. 

•  ftp .  cs .  Cornell .  edu  (Cornell  University) 

•  ftp . stolaf .  edu  (St.  Olaf  College) 

In  either  case,  use  the  file-transfer  program  ftp  to  open  a  connection  to  the 
desired  host.  Use  the  login  name  anonymous,  and  provide  your  own  Internet 
address  as  the  password. 

After  logging  in.  issue  the  ftp  command  cd  pub/trainset  to  access  the 
Trainset  distribution  directory.  Among  the  files  in  that  directory  are: 

•  README,  which  briefly  describes  Trainset  and  the  contents  of  the  distri¬ 
bution  directory, 

•  install  .dvi,  instedlation  manual  for  Trainset  (in  output  format). 

•  ts.dvi,  the  text  of  this  manual,^  and 

•  trainset.tar .Z,  the  source  code  package  for  Trainset. 

See  the  manual  page  for  ftp{\)  for  file  transfer  instructions.  Use  ftp  file  type 
bineo’y  for  .dvi  and  .tar.Z  files.  The  source  code  package  trainset  .tar  .Z 
may  be  unpacked  on  most  Unix  systems  by  issuing  the  following  command: 

V,  zcat  trainset  .tar.  Z  I  tar  xvf  - 
See  the  manual  pages  for  compress(l)  and  tar(])  for  more  information  about 
this  unpacking  procedure. 


*To  print  this  manutd  complete  with  figures,  install  Trainset  at  your  local  site  and  follow 
the  printing  instructions  provided  in  the  installation  manual. 
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Chapter  1 


Trainset  User’s  Guide 


1.1  Getting  Started 

Trainset  consists  of  programs  to  support  interaction  with  a  simulated  railroad. 
Users  can  control  the  railroad  manually  and  watch  it  in  action  by  using  graphics 
monitor  programs.  In  addition,  computer  programs,  called  control  programs. 
may  be  written  to  control  a  Trainset  railroad. 

The  rest  of  this  section  gives  you  a  chance  to  get  acquainted  with  Trainset. 
In  subsequent  sections  we  explain  how  to  create  and  run  your  own  railroad 
layout  and  how  to  u,se  the  ACI  library. 

1.1.1  Invoking  the  Programs 

To  start  the  Trainset  software,  enter  the  following  command, 
y.  ts 

(The  symbol '/.  is  assumed  to  be  your  shell  prompt.)  Three  windows  will  open 
on  your  display,  as  shown  in  Figure  1.1.  One  of  these,  the  Simulator  Window, 
is  a  terminal  window  that  displays  messages  from  the  simulation.  The  other  two 
windows  make  up  the  graphics  monitor.  The  Viewer  window  shows  the  current 
positions  of  the  railroad  tracks  and  trains  in  a  simulation.  The  Control  Pauiel 
window  has  controls  and  indicators,  including  pushbuttons  and  slide  bars;  it  is 
a  graphical  interface  for  controlling  trains  and  switch  blocks  manuedly.* 

The  sample  railroad  layout  displayed  in  the  Viewer  window  of  Figure  1.1 
has  two  trains  and  24  blocks.^  Each  train  has  two  ends;  one  is  called  the  head 

'The  names  of  the  programs  that  comprise  Trainset  arc  tain  for  the  simulator,  tsvies  for 
the  VisBsr,  tspanal  for  the  Control  Panol  and  tssd  for  the  layout  editor,  tsad  is  discussed 
in  Section  1.2  below. 

c6Lreful  reader  may  observe  that  the  24  block  identifiers  in  Figure  1.1  range  from  1  to 
5  and  7  to  25.  Identifier  6  is  associated  with  a  subblock  of  the  cross  block  cr  6,  as  explained 
in  Section  2.2.3. 
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Figure  1.1:  Sample  railroad  layout. 


4 


(indicated  by  an  angle  bracket)  and  the  other  is  called  the  tail  (indicated  by  a 
square  bracket).  A  block’s  type  (see  Section  2.2)  is  defined  by  its  label: 

rg  for  rtgular  blocks, 

St  for  station  blocks, 

jn  for  join  blocks, 

cr  for  cross  blocks  and 

SB  for  switch  blocks. 

Most  blocks  in  the  layout  of  Figure  1.1  are  represented  by  straight  lines  or  arcs, 
e.g.,  those  labelled  rg  1,  rg  2  and  st  11.  Five  such  blocks  are  thickened  to 
indicate  that  they  are  occupied  by  a  irciin.  Three  blocks  (cr  S.  jn  8  and  sh  14) 
have  other  block  types  that  are  represented  by  circled  symbols  in  the  layout. 

The  control  panel  comprises  one  subwindow  for  each  train  and  a  pushbutton 
for  each  switch  block.  Each  switch  block's  pushbutton  can  toggle  that  switch 
block’s  setting  between  the  straight  and  turned  settings.  Each  train’s  subwindow 
includes  the  following  controls  and  indicators. 

•  Two  slide  bars  labelled  Speed  and  Goal  that  display  the  train’s  current 
speed  and  the  goal  speed  desired  for  that  train. 

•  A  slide  bar  labelled  Throttle  for  setting  a  new  goal  speed.  An  operational 
train  accelerates  or  decelerates  when  its  goal  speed  differs  from  its  current 
speed. 

•  Two  labels  showing  the  name  of  the  train  (e.g..  Train  l)  and  its  state 
(Operational.  Derailed  or  Collided). 

•  Two  indicator  lights,  EmerStop  and  StaStop.  The  EmerStop  light  is  illu¬ 
minated  while  the  tr^lin  is  performing  an  emergency  stop.  The  StaStop 
light  is  illuminated  when  the  train  is  capable  of  performing  a  station  stop, 
described  later. 

•  Three  pushbuttons,  EmerStop.  StaStop  and  Reverse.  The  EmerStop 
pushbutton  can  be  used  to  begin  an  emergency  slop  of  the  train.  The 
StaStop  pushbutton  can  be  used  to  enable  the  station-stop  feature  for 
that  train.  The  Reverse  pushbutton  changes  the  direction  of  the  train’s 
motion  if  the  train  is  stopped. 

1.1.2  Using  the  Control  Panel 

The  best  way  to  familiarize  yourself  with  the  features  of  the  Control  Panel  is  to 
try  them,  observing  their  effects  as  displayed  in  the  Viewer  wii.  iow.  Below  are 
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some  suggested  steps  for  getting  acquainted  with  the  system,  using  tie-  sample 
layout  of  Figure  1,1.'^ 

VVhen  describing  graphics  manqiulations.  we  will  use  the  following  terms  for 
mouse-oriented  input  operations.  The  mou.se  huiton  to  press  and  rele;ise  is  liie 
left  mouse  button  (for  standard  workstation  window  managers) 

•  To  dick  on  a  pushbutton  or  icon,  move  the  mouse  pointer  into  the  push¬ 
button  or  icon  area,  then  press  the  mouse  button  down  and  release  it 
immediately. 

•  To  drag  from  oju  point  to  auotktr  in  a  window,  position  the  mouse  cursor 
at  the  starting  point,  then  pre.ss  the  mouse  button  and  hold  it  dowu 
while  moving  the  mouse  icon  to  the  finish  point.  Finally,  release  the 
mouse  button. 

•  To  drag  a  sltdf  bar  to  a  valuf  r.  first  position  the  mouse  pointer  over  the 
inner  region  that  contains  the  indicator  arrow  for  that  slide  bar  graphic. 
Then,  press  the  mouse  button  and  hold  it  down  while  moving  the  mouse 
cursor  right  or  left  until  the  desired  value  r  is  displayed  on  the  numerical 
display.  Finally,  release  the  mouse  button.  Due  to  variation  in  graphics 
display  resolution,  it  may  not  be  possible  to  enter  arbitrary  desired  values 
using  a  slide  bar. 

Before  starting,  identify  the  controls  and  indicators  for  each  train  and  switch 
block  in  the  Control  °anel  wdridow.  The  Speed,  Goal  and  Throttle  slid*  bars 
for  each  train  display  the  initial  value  zero.  Each  train  is  operatic'.”, .it.  and 
neither  of  the  StaStop  and  EmerStop  indicator  lights  is  illuminated 

[Click  (once)  on  the  pushbutton  for  the  switch  block  sw  14 

When  you  click  on  the  pushbutton,  the  switch  block  toggles  between  the  straight 
and  turned  settings.  Observe  that  there  is  a  delay  after  pressing  the  pushbutton 
before  the  switch  block  setting  actually  changes  on  the  screen.  This  delay  has 
two  causes;  communication  time  and  the  time  that  it  actually  takes  for  a  switch 
block,  which  is  a  large  mechanical  device,  to  change  setting. 

Click  on  the  switch  block  pushbutton  agciin  to  toggle  the  switch 
block  back  to  the  straight  .setting. 

Click  on  the  StaStop  and  EmerStop  pushbuttons  for  Train  2. 

Do  not  click  on  the  Reverse  pushbutton  for  Train  2  nor  any 
pushbuttons  for  Train  1  at  this  time. 

■^Suggested  actions  are  enclosed  in  boxes. 


6 


VVlien  the  StaStop  indicator  light  is  on.  vve  .say  that  train  is  in  .‘.taltou 
slop  mode:  likewise,  the  EmerStop  indicator  light  shovv.s  whetlier  the  train  is 
in  emergency-slop  mode.  Note  that  the  StaStop  indicator  light  ran  be  illunii- 
nated.  but  the  EmerStop  indicator  light  cannot  be  ilhirninaled  yet  An  opera¬ 
tional  train's  station-stop  mode  can  be  enabled  or  di.sabled  whether  that  tram 
is  moving  or  not.  Emergency-stop  mode  cannot  be  enabled  for  a  tram  unless 
that  train  is  moving. 

VVe  are  now  ready  to  set  a  train  in  motion. 

Accelerate  Train  1  by  dragging  the  Throttle  slide  bar  for  that 
train  to  a  value  near  40  (m/.sec). 

Notice  that  several  things  liappen  when  you  do  this. 

•  The  goal  speed  indicator,  labelled  Goal,  now  shows  the  throttle  value. 

•  The  current  .speed  indicator,  labelled  Speed,  begins  changing  from  the 
previous  speed  (zero  in  this  case)  towards  the  goal  speed. 

•  The  train  at  the  top  of  the  Viewer  window  begins  moving  (forward  towards 
the  left,  in  this  case). 

The  goal  speed  is  not  reached  instantaneously.  A  train  ordinarily  changes  speed 
at  a  fixed  rate  of  acceleration,  as  explained  in  Section  2.3.2.  and  it  takes  time 
to  accelerate  from  0  to  40  m/sec. 

Observe  that  a  block  is  highlighted  in  the  Viewer  window  if  any  part  of  that 
block  is  occupied  by  a  train. 

Drag  the  Throttle  slide  bar  to  about  .55  m/sec,  then  drag  it  to 
about  45  m/sec  before  the  train  has  completed  accelerating  to 
55  m/sec. 

This  exercise  shows  that  a  new  goal  speed  value  overrides  a  previous  one  when 
the  throttle  is  changed,  even  if  a  previous  goal  speed  has  not  yet  been  reached. 

There  is  a  maximum  speed  limit  of  60  m/sec  for  each  block  in  the  sample 
layout  of  Figure  1.1.  If  a  train  exceeds  this  limit,  that  train  derails.  All  minimum 
speed  limits  in  the  sample  layout  are  zero.  Using  the  editor  tsed  (see  Section  1,2 
below)  it  is  possible  to  create  new  layouts  having  different  shapes  and  block 
speed  limits  or  to  modify  the  features  of  an  existing  layout.  However,  there  i.s 
no  provision  for  changing  the  attributes  of  a  layout  while  it  is  being  simulated. 

Next,  request  an  emergency  stop. 

1 . ■  '  ■■  ...  ... 


Click  on  the  EmerStop  pushbutton  for  Train  1. 


Observe  that  the  EmerStop  indicator  liglu  is  iiluniinated  while  an  emergency 
stop  is  in  progress  and  goes  off  as  soon  as  the  slop  lias  completed.  Another  way 
to  stop  a  train  is  by  simply  setting  that  train's  throttle  to  zero.  An  emergency 
stop,  like  a  throttle  change,  overrides  any  prior  motion  plan.  Thus,  during  an 
emergency  stop  a  train's  Goal  speed  is  zero  and  its  current  speed  decreases 
toward  zero.  There  are  two  important  differences  between  using  the  throttle  to 
decelerate  to  zero  and  using  emergency  stop. 

•  Emergency  stops  use  a  larger  deceleration  rate. 

•  Nothing  can  override  an  emergency  stop,  other  than  derailment  or  collision 
of  the  train. 

In  particular,  dragging  the  Throttle  slide  bar  has  no  effect  during  an  emergency 
stop.  Nor  does  an  emergency  stop  cause  the  throttle  bar  to  move.  The  throttle 
is  simply  ignored  until  the  emergency  stop  has  completed  and  the  throttle  is 
dragged  again. 

Station  blocks  differ  from  regular  blocks  in  that  they  have  a  station-stop 
feature.  To  test  this  feature,  perform  the  following  steps. 

Click  on  the  StaStop  pushbutton  of  Train  1  so  that  the  StaStop 
indicator  light  becomes  illuminated  (stat'^'n-slop  mode). 


1  Drag  that  train's  Throttle  slide  bar  to  30  m/sec  or  less. 

The  next  time  that  Train  1  enters  a  station  block  (either  st  11  or  st  16),  it 
W'ill  immediately  begin  slowing  down  so  that  it  comes  to  a  halt  exactly  at  the 
opposite  terminator  of  that  block.  Three  conditions  are  required  for  a  train  to 
begin  performing  a  station  stop. 

•  That  train  must  have  station-stop  mode  enabled. 

•  That  train  must  have  speed  at  most  the  station-stop  speed. 

•  That  train  must  be  entering  a  station  block. 

The  station-stop  speed  (30  m/sec  in  the  sample  layout  of  Figure  1 . 1 )  is  specified 
for  each  station  block  when  a  layout  is  created. 

Observe  that  the  station-stop  indicator  automatically  '{ui-';  off  as  soon  as  a 
station  stop  begins. 

Allow  Train  1  to  complete  a  station  stop. 

Unlike  emergency  stops,  it  is  possible  to  abort  a  station  stop  by  changing 
the  throttle  value  for  the  train  involved.  If  a  station  stop  is  aborted,  then  no 
station  .stop  is  performed  until  the  three  station-stop  conditions  are  again  met 
on  entry  into  a  station  block. 

A  train's  direction  can  only  be  changed  when  that  train  is  slopped. 
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Click  on  Train  I  s  Reverse  pushbutton  (once)  vvliile  that  train  is 
stopped. 


Then  drag  that  train’s  throttle  slide  bar  to  a  positive  value,  e.g.. 

30  (m/sec). 

Train  1  will  begin  to  move  back"'a.ds;  that  is.  the  head-end  retreats  and  the 
tail-end  advances. 

Up  to  now,  both  trains  have  remained  in  the  Operational  state.  In  order 
to  become  acqUEiinted  with  another  train  state,  try  the  following. 

Let  Train  1  travel  (backwards)  around  the  layout  until  it  derails 
at  block  jn  8. 

When  a  train  enters  a  join  block  (such  as  jn  8)  from  the  tail  terminator 
(the  one  attached  to  rg  9  in  the  sample  layout),  then  the  tram  will  derail.  If  a 
train  derails,  the  state  label  for  that  train  changes  to  Derailed  and  the  train 
stops  moving. 

Trains  that  are  not  Operational  do  not  respond  to  commands.  Thus,  once  a 
train  derails,  there  is  no  way  to  set  that  train  in  motion  again,  short  of  starting 
another  simulation.  Page  35  lists  all  the  conditions  under  which  a  train  will 
derail. 


Click  on  the  pushbutton  for  switch  block  sw  14  once  so  that  the 
switch  block  changes  to  the  turned  setting. 


Drag  the  Throttle  slide  bar  for  Train  2  to  a  positive  value,  e.g.. 
30  m/sec. 


Observe  that  attempting  to  enter  a  disconnected  terminator  of  a  switch  block 
would  cause  a  train  to  derail. 

Finally,  observe  what  happens  when  trains  collide. 

Allow  Train  2  to  continue  until  it  collides  with  Train  1. _ 

The  state  labels  of  both  trains  involved  in  a  collision  change  to  Collided.  Hence¬ 
forth,  neither  train  will  respond  to  any  commands,  so  the  demonstration  has 
ended— in  disaster!  Fortunately,  simulated  trains  are  inexpensive  to  replace. 
Page  36  lists  all  possible  collision  conditions. 


].1,3  Shutting  the  Programs  Down 

The  programs  that  comprise  Trainset  may  be  shut  down  by  selecting  Quit 
All  in  the  Conuaand  menu  of  the  Control  Panel  or  Viewer. 
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Exercises 


1.  Start  a  simulation  of  the  default  layout  by  issuing  the  ts  command.  Set 
both  trains  in  motion  around  the  track  simultaneously,  with  Train  1  trav¬ 
elling  forward  and  Train  2  travelling  backward, 

2.  Perform  Exercise  1.  Then,  begin  toggling  the  setting  of  the  switch  block 
SR  14  so  that  Train  1  edways  passe.s  through  sw  14  when  sb  14  is  straight 
and  Train  2  always  passes  through  that  switch  block  when  it  is  turned. 

Note;  This  is  not  as  easy  as  it  may  sound!  Keeping  both  trains  travelling 
along  different  paths  in  this  layout  is  a  challenge,  particularly  if  both  are 
moving  as  fast  as  possible.  Train  speed  adjustments  and  swdtch  block 
setting  changes  must  be  coordinated  and  must  be  issued  far  enough  in 
advance  so  that  the  trains  neither  collide  nor  occupy  a  switch  block  while 
it  changes  setting. 


1.2  How  to  Build  a  Layout  of  Blocks  and  Trains 

tsed  is  am  interactive  graphics  editor  for  defining  and  modifying  railroad  layouts. 

1.2.1  Invoking  tsed 

To  start  tsed,  enter  the  following  command. 

%  tsed  [filename] 

The  editor  may  also  be  invoked  by  entering; 
y,  ts  -edit  [filename] 

When  tsed  is  started,  two  windows  appear  on  your  display,  as  shown  in 
Figure  1.2.  The  larger  window  that  is  overlaid  with  a  grid  pattern  is  the  canvas 
window  (Figure  1.2a).  A  railroad  layout  can  be  created  in  the  canvas  window. 
The  distance  between  two  adjacent  parallel  dotted  lines  in  the  grid  is  called  a 
grid  division. 

The  smaller  window  is  called  the  toots  window  (Figure  1.2b).  It  consists  of 
twelve  icons  representing  operations  called  the  tools  that  are  available  in  tsed 
for  creating  and  modifying  blocks  and  trains.  The  tools  are  applied  using  the 
mouse  operations  described  on  Page  6  Figure  1.3  shows  the  tools  window 
together  with  the  names  of  its  tools. 

The  tools  window  contains  one  or  more  tools  for  each  of  the  five  types  of 
blocks  in  Trainset.  Note  that  the  tools  window  includes  two  tools  for  creating 
switch  blocks.  The  Switch  Block  1  and  Switch  Block  2  tools  differ  in  the 
orientation  of  the  switch  block;  each  is  a  mirror  image  of  the  other.  Also,  there 
are  three  tools  for  creating  regular  blocks;  Straight  Block,  Arc  Block  1  and 
Arc  Block  2.  A  straight  block  is  a  regular  block  consisting  of  a  line  segment, 
and  an  arc  block  is  a  regular  block  consisting  of  a  circular  segment.  Arc  Block  1 
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Figure  1.2:  tsed  Windows 
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Figure  1.3:  Annotated  Tools  Window 
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and  Arc  Block  2  differ  only  in  the  radius  of  the  arcs  they  create.  The  Arc 
Block  1  tool  creates  arcs  with  radius  two  grid  divisions,  and  the  Arc  Block  2 
tool  creates  arcs  with  radius  four  grid  divisions. 

The  remainder  of  this  section  is  a  two-part  tutorial  on  using  tsed  for  creating 
and  editing  railroad  layouts.  Section  1.2.2  introduces  you  to  the  various  tsed 
tools.  A  series  of  exercises  demonstrates  how  to  construct  a  layout  and  how  to 
make  simple  editing  changes.  Section  1.2.3  explains  how  to  set  attributes  such 
as  block  speed  limits,  how  to  save  a  layout  in  a  file,  and  how  to  exit  from  the 
editor. 

1.2.2  Using  the  tsed  tools 

The  Current  Tool 

In  tsed,  one  tool  is  enabled  at  any  given  time:  it  is  called  the  current  tool.  The 
current  tool  is  indicated  in  the  tools  window  by  being  highlighted.  The  message 
area  at  the  bottom  of  the  canvas  w'indow  also  displays  the  name  of  the  current 
tool.  On  startup,  Select  is  the  current  tool. 

Click  on  a  tool  icon  other  than  Select  to  choose  a  different  current 

tool.  Repeat  one  or  more  times. 


Regular  and  Station  Blocks 

Straight  regular  blocks  and  station  blocks  are  created  in  a  layout  by  dragging 
with  the  mouse  from  one  point  to  another  in  the  canvas  window  when  the 
corresponding  straight  block  or  station  block  is  the  current  tool.  This  procedure 
creates  a  line  segment  between  the  starting  zind  stopping  points  of  the  drag 
operation.  The  starting  point  is  called  the  head  iermtnator  of  the  block,  and 
the  stopping  point  is  called  the  tail  terminator. 

Click  on  the  Straight  Block  tool  icon.  I 


Create  a  horizontal  regular  block  by  dragging  from  right  to  left 
starting  near  the  middle  of  the  canvas  window,  as  shown  in  Fig¬ 
ure  1.4a. 


All  linear  blocks  (Straight  and  Station)  created  by  tsed  are  constrained 
to  be  vertical,  horizontal  or  at  a  ±45”  diagonal.  To  aid  in  alignment,  tsed 
enforces  additional  constraints  on  the  placement  and  length  of  a  block  relative 
to  the  dimensions  of  the  canvas  window  grid. 

Click  on  the  Station  Block  tool  icon. 


12 


When  a  new  block  is  created,  tsed  establishes  a  connection  with  an  existing 
block  if  the  new  head  terminator  is  within  a  few  pixels  of  an  existing  terminator, 
tsed  also  constrains  the  slope  of  the  new  block  to  match  the  slope  of  the  existing 
block  at  that  terminator. 

Station  blocks  and  straight  regular  blocks  appear  graphically  to  be  identical 
except  for  their  labels.  Regular  blocks  (whether  straight  or  arc)  are  labelled  rg. 
and  station  blocks  are  labelled  st. 

The  Erase  and  Select  tools  are  used  for  modifying  objects  already  on  the 
canvas  window.  Erase  enables  you  to  remove  a  block  or  treiin  that  you  have 
created.  Select  enables  you  to  reposition  the  label  for  a  block  or  to  designate 
a  block  whose  attributes  you  wish  to  change. 
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The  result  of  these  changes  are  shown  in  Figure  1.4c. 

Arc  blocks  are  created  by  dragging  when  the  current  tool  is  Arc  Block  1  or 
Arc  Block  2.  The  starting  point  of  the  drag  operation  determines  the  location 
of  the  arc  block’s  head  terminator.  The  extent  of  the  arc  is  determined  by  the 
ending  point  of  the  drag  operation  and  depends  on  the  location  of  the  head 
terminator  and,  if  the  arc  block  is  attached  to  another  block,  the  slope  of  that 
block. 

Click  on  the  Arc  Block  1  tool  icon. 


Create  an  arc  block  connected  to  the  station  bloc,  oy  dragging 
from  the  left  endpoint  of  the  station  block  toward  a  point  that 
produces  a  90®  arc  pointing  dow'nward,  as  shown  in  Figure  ].4d. 


When  using  the  Straight  Block.  Station  Block,  Arc  Block  1  or  Arc 
Block  2  tools,  you  can  cancel  creation  of  a  bloc’  after  a  drag  operation  has 
already  been  initiated  by  finishing  that  drag  operation  within  a  few  pixels  of  its 
starting  point. 

Start  dragging  to  create  another  arc  block  connected  to  the  last 
arc  block,  then  cancel  the  creation  of  a  new  block  by  finishing  that 
drag  operation  at  its  starling  point. 


Iconic  Blocks:  Crosses,  Joins  and  Switches 

The  Cross  Block,  Join  Block,  Switch  Block  1  and  Switch  Block  2  tools 
always  create  blocks  that  have  a  fixed  size  and  shape.  In  tsed,  these  blocks  are 
referred  to  as  iconic  blocks.  They  are  created  by  clicking  with  the  mouse  rather 
than  by  dragging. 

When  an  iconic-block  tool  is  current  and  the  mouse  cursor  is  in  the  canvas 
window,  the  cursor  takes  the  form  of  the  icon  for  the  current  tool.  Along 
the  outer  circle  of  such  a  cursor  are  enlarged  points  called  hot  spots  at  which 
connections  with  other  blocks  can  be  made. 

Click  on  the  Join  Block  tool  icon.  Observe  that  the  mouse  cursor 
changes  to  the  form  of  a  join  block  whenever  the  cursor  is  in  the 
canvas  window. 


Position  the  mouse  cursor  so  that  the  hot  spot  at  its  right  head 
is  over  the  unattached  terminator  of  the  arc  block.  This  requires 
slight  overlapping  between  the  arc  block  and  the  join-block  cursor; 
see  Figure  1.5a. 
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(a)  Before  Clicking 


(b)  After  Clicking 


Figure  1.5:  Join  Block  Creation 


Now  click  with  the  mouse  and  create  the  join  block  of  Figure  1.5b. 

Note  that  the  newly  created  join  block  is  constrained  so  that  the  slope  of  the 
join  block  and  the  slope  of  the  arc  block  agree  at  their  common  terminator. 

tsed  does  not  make  more  than  one  connection  when  an  iconic  block  is  cre¬ 
ated.  Thus,  during  an  editing  session,  it  is  probably  best  to  create  iconic  blocks 
before  creating  the  regular  and  station  blocks  they  are  attached  to. 

The  Rotate  tool  enables  you  to  rotate  an  iconic  block  clockwise  by  one  hot 
spot. 

Click  on  the  Rotate  tool  icon. 


Now  click  on  the  join  block  created  in  step  15.  Observe  that  the 
join  block  labelled  jn  4  rotates  so  that  its  tail  terminator  becomes 
the  terminator  attached  to  the  arc  block. 


Click  on  the  join  block  a  second  time  to  rotate  again. 

If  an  iconic  block  is  not  connected  to  any  other  block,  the  Rotate  tool 
rotates  it  by  one-eighth  turns.  If  a  switch  block  is  rotated  through  a  full  circle 
using  the  Rotate  tool,  it  changes  orientation. 

Trains 

A  train  may  be  created  in  a  layout  by  dragging  when  TVain  is  the  current 
tool.  The  drag  operation  begins  at  the  position  desired  for  the  head  end  of  a 
train,  continues  along  the  blocks  to  be  occupied  by  that  train,  and  stops  at  the 
position  desired  for  that  train’s  tail  end.  The  head  end  of  a  train  is  indicated 
in  the  layout  by  an  angle  bracket,  and  the  tail  end  is  indicated  by  a  square 
bracket.  Ail  blocks  occupied  by  a  trrun  are  highlighted.  The  head  end  of  a  tram 
is  constrained  by  '  ^ed  to  start  in  a  regular  or  station  block. 
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Figure  1.6;  Ov^d  Layout 
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Erase  all  blocks  currently  on  the  layout.  Then,  create  an  oval 
layout  as  in  Figure  1.6a  made  of  four  straight  blocks  and  four  arc 
blocks,  using  the  Straight  Block  and  Arc  Block  1  tools. 

It  is  not  necessary  that  the  block  identifiers,  i.e.,  the  numbers  in  the  labels, 
match  those  in  Figure  1.6a. 

Click  on  the  Train  tool  icon. 


Create  a  train  on  the  oval  by  dragging  clockwise  from  the  point 
marked  A  to  that  marked  B  in  Figure  1.6a,  resulting  in  Fig- 
ure  1.6b. _ 

If,  while  creating  a  train,  you  drag  across  the  starting  point,  the  brackets 
that  indicate  train  ends  reverse  their  directions.  Also,  observe  that  a  whole 
block  is  highlighted  if  any  part  of  that  block  is  occupied  by  a  train. 

You  should  now  feel  comfortable  with  the  basic  drag  and  click  operations 
for  creating  blocks  and  trains  in  a  layout.  In  the  next  part  of  this  tsed  tutorial, 
you  will  learn  how  to  store  a  layout  in  a  file,  how  to  specify  attributes  such  as 
speed  limits  for  individual  blocks,  and  how  to  exit  tsed. 

If  you  would  prefer  to  return  to  this  tutorial  at  a  later  time,  select  Quit'* 
from  the  File  menu  now,  and  invoke  tsed  again  when  you  are  ready  for  the 
remainder  of  the  tutorial.  There  is  no  need  to  save  your  present  work,  since  it 
will  not  be  used  in  the  second  part  of  the  tutorial. 

1.2.3  Creating  a  figure-eight  layout  file 

Our  goal  is  to  create  the  figure-eight  layout  illustrated  in  Figure  1.7  and  then 
save  that  layout  in  a  file  mylayout.l.  All  blocks  in  the  layout  should  have 
minimum  speed  of  0  (m/sec)  and  maximum  speed  of  70,  except  that  the  station 
blocks  at  the  top  and  bottom  of  the  layout  are  to  have  minimum  speed  of  0  and 
maximum  speed  of  50. 

Select  Hew  from  the  File  menu.  If  you  are  continuing  from  the  first 
part  of  the  tutorieJ,  tsed  will  ask  if  you  wish  to  discard  changes 
in  the  canvas  window;  click  on  the  Yes  button.  In  response  to  the 
prompt,  enter  mylayout  as  the  name  of  the  file  to  be  created. 

By  invoking  the  Hew  command  above,  mylayout.l  becomes  the  current  file 
name.  This  name  is  indicated  in  the  title  for  the  canvas  window.  Prior  to  the 
Hew  command  there  was  no  current  file  name.  When  naming  a  file,  the  extension 
.1  is  automatically  appended  by  tsed  if  you  do  not  include  it.  Pathnames  that 

^Quit  will  be  discussed  in  detail  on  Page  21. 
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Figure  1.7;  A  figure-eight  layout 
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Figure  1.8;  Change  Default  Block  Attributes  subwindow 

do  not  begin  with  a  slash  V’  ^re  interpreted  relative  to  the  current  working 
directory. 

The  default  minimum  and  mtiximum  speeds  for  blocks  can  be  changed  by 
choosing  the  Change  Default  Block  Attributes  entry  from  the  Customize 
menu.  A  changed  default  value  applies  to  blocks  created  after  llie  change;  it 
does  not  affect  blocks  already  created.  Change  Default  Block  Attributes  is 
itself  a  menu  whose  subentries  are  the  various  block  types. 

Change  the  default  attributes  for  straight  blocks  by  choosing 
Change  Default  Block  Attributes  from  the  Customize  menu 
and  moving  the  cursor  to  the  right  until  the  subentries  appear. 

Select  the  Straight  subentry. 

After  this  step,  a  subwindow  will  appear  that  contains  three  slide  bars  as 
shown  in  Figure  1.8.  The  slide  bar  on  the  top  determines  the  minimum  speed 
for  streiight  blocks  and  is  normally  0.  The  slide  bar  in  the  middle  determines 
the  maximum  speed,  which  is  60  at  present.  The  slide  bar  on  the  bottom  is 
disabled  for  straight  blocks  since  it  defines  the  station  stop  speed,  an  attribute 
that  is  only  applicable  to  station  blocks. 

Set  a  new  maximum  speed  by  dragging  the  middle  slide  bar  to  70. 

Leave  the  minimum  speed  at  0. 


Click  on  the  Change  pushbutton  to  make  the  new  default  speed 
limits  effective. _ 

The  steps  above  change  the  default  maximum  speed  for  straight  blocks  only. 
We  also  need  arc  blocks  and  cross  blocks  that  have  a  maximum  speed  of  70. 


19 


Change  the  default  tiiaxinium speed  to  70  for  arc  blocks,  usiiin  the! 

Arc  subeiitry  in  llie  Change  Default  Block  Attributes  menu 
under  Customize  and  proceeding  as  above. _ i 

Also  change  tlie  default  rnaxiriiuin  speed  to  70  for  cross  blocks 

You  are  now  ready  to  create  the  blocks  of  your  layout  Refer  to  figure  17 
for  illustration  of  the  steps  below. 

j  Create  a  cross  block  near  the  center  of  the  layout  at  an  intersection 
point  of  two  perpendicular  dotted  lines  in  the  grid 


Rotate  the  new  cross  block  once  using  the  Rotate  tool.  The 
subblocks  of  the  cross  should  form  an  'x'  as  opposed  to  a  '+'. 


Create  two  straight  blocks  of  exactly  the  same  length,  eacli  form¬ 
ing  the  diagonal  of  a  square  with  sides  about  4  grid  divisions  long, 
so  that  the  head  terminators  of  tlie  straight  blocks  are  attached 
to  the  upper  hot  spots  of  the  cross  block. 

Note  that  the  grid  assists  you  in  determining  vviieri  blocks  have  exactly  the 
same  length. 

Create  two  arc  blocks  with  135“  extent  and  head  terminators  at¬ 
tached  to  the  straight  blocks  that  you  just  created. 


Create  a  station  block  that  connects  to  both  unattached  tertiiina-  j 
tors  of  the  arc  blocks.  _ 

The  attributes  of  an  individual  block  may  be  customized  by  selecting  that 
block  with  the  Select  tool  and  choosing  Change  Block  Attributes  from  the 
Customize  menu. 

Click  on  the  Select  tool  icon.  | 


Click  on  station  block  st  7  in  the  canvas  window  to  select  it  for 
customization. 


Clioose  Change  Block  Attributes  from  the  Customize  menu. 


In  the  subwindow  that  appears,  set  a  new  maximum  speed  by 
dragging  the  slide  bar  in  the  middle  to  50. 

The  station  stop  speed  is  another  attribute  that  may  be  adjusted  for  station 
blocks  using  Change  Block  Attributes.  (See  Section  2.2.5  for  a  discussion  of 
the  station  stop  speed.)  VVe  will  leave  the  default  value  at  30  for  this  layout. 
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Create  the  lower  portion  of  a  figure-eight  layout  using  a  procedure 
similar  to  the  previous  seven  steps. 


Place  a  train  on  the  figure-eight  layout. 


You  have  now  created  the  desired  figure-eight  layout.  It  is  time  to  save  your 
work  and  exit  from  the  editor. 


Save  the  figure-eight  layout  by  choosing  Save  from  the  File  menu. 

Either  the  Save  entry  or  the  Save  as  . . .  entry  in  the  File  menu  may  be 
used  to  save  your  work  in  a  file.  The  difference  is  that  Save  as  . . .  always 
prompts  you  for  a  file  name,  while  Save  uses  the  current  file  name  if  there  is 
one. 

Finally,  end  the  editing  session: 

Exit  tsed  by  choosing  Quit  from  the  File  menu. 

The  Quit  command  checks  for  any  unsaved  changes  before  exiting.  If  any 
are  found.  Quit  gives  you  the  option  of  waiting  them  to  a  file  first.  The  Close 
command  is  similar  to  Quit,  except  tsed  does  not  exit  after  checking  for  unsaved 
changes.  Instead,  a  Close  causes  tsed  to  enter  a  stale  with  an  empty  canvas 
w'indow  and  no  current  filename. 


1.3  How  to  Run  a  Layout 

A  railroad  layout  mylayout  created  using  tsed  can  be  simulated  by  issuing  the 
following  command, 

%  ts  -layout  mylayout 

A  Trainset  simulation  will  start  and  search  for  a  file  called  mylayout.  1,  first 
searching  in  the  current  working  directory,  then  in  the  standard  location  for 
layouts,  as  explained  in  the  manual  page  for  ts  in  Appendix  D. 

1.4  Control  Programs 

The  Automatic  Control  Interface  (ACI)  is  a  library  of  procedures  and  data 
structure  definitions  for  writing  programs  that  control  a  Trainset  railroad. 

The  principal  data  type  associated  with  the  ACI.  LayoutData.  represents 
various  attributes  of  the  blocks  and  trains  in  a  railroad  layout.  LayoutData  is 
described  in  Section  3.2  and  defined  in  Appendix  B.l. 

The  ACI  routine.s  may  be  classified  into  five  categories. 
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1.  The  ACI  GetDosnload  procedure  establishes  a  network  conneclion  with  a 
running  railroad  simulator  and  receives  a  report  of  the  state  of  the  railroad 
being  simulated.  GetDoonload  returns  a  pointer  to  an  internally  allocated 
data  structure  of  type  LayoutData  holding  the  state  information  that  has 
been  received.  See  Section  3.2  for  further  details. 

2.  ACI  commands  enable  a  program  to  change  certain  attributes  of  blocks 
and  trains.  Seven  command  types  are  available. 

•  SetSwitch  initiates  a  setting  change  for  a  switch  block, 

•  Accelerate  and  Decelerate  initiate  changing  the  speed  of  a  train 
at  a  constant  rate  for  a  specified  time  period. 

•  SetSpeed  initiates  changing  the  speed  of  a  train  towards  a  specified 
goal  speed. 

•  SetDirection  changes  the  direction  of  a  train  that  is  stopped. 

•  EctergencyStop  halts  a  train  using  a  deceleration  rate  that  is  quicker 
than  the  rate  for  Decelerate. 

•  StationStop  enables  a  train  to  come  to  a  complete  stop  at  a  known 
location  in  a  station  block,  provided  that  the  train  enters  that  station 
block  slowly  enough. 

See  Section  3.3  for  more  details  about  ACI  commands. 

3.  ACI  queries  enable  a  control  program  to  obtain  state  information  about  a 
railroad  after  a  download  has  been  received.  Four  query  types  are  avail¬ 
able. 


•  GetBlockOccupancy  indicates  whether  a  specified  block  is  occupied. 

•  GetSsitchPosit  returns  the  setting  of  a  switch  block. 

•  GetTrainStatus  indicates  whether  a  train  is  operat'onal. 

•  GetTrainMotion  indicates  whether  a  train  is  moving. 

See  Section  3.4  for  more  information. 

4.  ACI  voting  service  procedures.  SetSeqNumber  and  NepSeqNumber.  interact 
with  a  command  arbitration  facility  in  the  simulator.  This  service  is  useful 
when  implementing  fault-tolerant  control  programs.  See  Section  3.5. 

5.  ACI  utility  procedures.  InitTimer.  GetTimer.  AHaitTimer,  CancelTiner 
and  Sleep,  provide  high-level  general  purpose  timing  facilities.  See  Sec¬ 
tion  3.6. 
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/*  demo.c  —  simple  demonstration  of  the  ACI  ♦/ 

[T]  #include  "aci.h"  /♦  ACI  definitions  and  declarations  */ 

#define  HAX.HQSTHAME  100 

[2]  #define  POLLIRG.INTERVAL  0.100  /•  Seconds  ♦/ 

#define  POLL I NO .TIMEOUT  200.0  /♦  Seconds  ♦/ 

#define  HULL  (void  *)  0  /•  generic  null  pointer  */ 

int  poll.timeout.f lag  =0;  /*  flag  for  terminating  polling  loops  */ 

*  set.poll.timeout.flag  is  executed  by  a  timer  that  is  used  to  prevent 
[sT]  *  infinite  polling  loops. 

^^^tim*************^^**:^****^***********************************************/ 

void 

set_poll_timeout_fla,'T() 

< 

poll.timeout.f lag++ ; 

} 

* 

*  This  program  shows  the  mechanics  of  the  ACI  layer  of  the  control 

*  program  interface,  by  initiating  a  connection  with  the  simulator, 

*  receiving  the  state  of  the  railroad,  moving  a  train,  and  making  some 

*  queries. 

* 

*^i*iHf*if^inHfiHi^t^tiit*i‘****A‘****’¥iHf»***m*************************4i**t^*^m****t**/ 

mainCargc,  argv) 
int  argc; 
char  ♦argv  □ ; 

{ 

char  ♦prognarae;  /♦  name  of  this  program  ♦/ 

char  ♦hostname  =  /♦  host  that  is  running  simulator  ♦/ 

int  simnum  =  C;  /♦  distinguishes  between  simulators  running  on  same  host  ♦/ 

Seconds  timeout  =  20.0;  /*  maximum  second  to  connect  to  simulator  */ 

LayoutData  ♦datap;  /♦  pointer  to  entire  received  railroad  state  info  ♦/ 

Figure  1.9:  demo.c,  an  example  using  the  ACI  (beginning). 
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[T]  TrainData  ♦tp;  /♦  pointers  to  parts  of  received  layout  data  */ 

BlockData  ♦bp; 

int  T  =  1,  B  =  1;  /*  identifiers  of  a  train  and  a  block  */ 

enuat  Occupancy  occ;  /*  return  values  from  queries  */ 
enuia  TrainNotion  tm; 
int  n;  /*  loop  counter  */ 

/• 

*  Collect  command  line  args 

*/ 

progname  =  ♦argy**; 
if  (argc) 

hostname  =  *aTgv++; 
if  (argc) 

simnum  =  atoi(*argv++) ; 
if  (argc) 

timeout  =  atof (*argv++); 

/* 

*  Coimect  and  get  the  state  of  the  railroad. 

*  Then,  use  received  values  to  check  the  identifiers  T  and  B. 

•/ 

[T|  datap  =  GetDownload(hostname,  simnum,  progname,  timeout); 
if  (datap  ==  (LayoutData  ♦)  0)  { 

printf ("couldn’t  get  initial  download ! \n" ) ; 
exit  (1); 

> 

[T|  if  (T  <=  1  I i  T  >=  datap->train_ct)  { 

printf  ("sample  train  ID  '/,d  out  of  range  [1 .  .’/.d]  !\n",  T,  datap->train_ct) ; 
exit  (1); 

} 

if  (B  <=  1  I  I  B  >=  datap->block_ct)  i 

printf  ("sample  block  ID  V,d  out  of  range  [1 .  .*/.d]  !\n",  B,  datap->block_ct) ; 
exit  (1); 

> 


Figure  1.9:  derao.c,  an  example  using  the  ACJ  (continued). 
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/* 

♦  Print  some  sample  values. 

*/ 


print! ("Nujnber  of  trains;  %d.  Humber  of  blocks;  */,d\n", 
datap->train_ct ,  datap->block_ct) ; 

tp  =  ftdatap->trains [T] ; 

print! ("Train  '/A  has  length  ‘/,.2f,  with  front  at  block  */td  offset  */,.2f\n", 
[T]  tp->length,  tp->front .block,  tp->front . off set) ; 

bp  =  ftdatap->blocks [B] ; 

print! ("Block  */.d  has  length  ‘/,.2f,  max  speed  y,.2f  and  min  speed  ‘/..2f\n", 
bp->length,  bp->max_speed,  bp->min_speed) ; 
if  (bp->type  ==  BT_REGULAR) 

printf("This  is  a  regular  block,  connected  to  blocks  */,d  and  y,d\n\n", 
[T]  bp->t.rg.tail,  bp->t .rg.head) ; 


/* 

*  Perform  some  accelerations  and  decelerations  of  train  T. 
*/ 


print! ("beginning  accelerationXn") ; 

[T|  Accelerated,  20.0); 

print! ("pausing. .  .\n'*) ; 

Sleep(25.0); 

print! ("beginning  decelerationVn") ; 

1 11 1  Decelerate(T,  5.0); 

/* 

*  Travel  until  block  B  is  occupied  (or  timeout  occurs) 

*/ 
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print! ("polling  until  block  '/.d  is  reached. .  .\n" ,  B); 
poll_timeout_flag  =  0; 

InitTimer(POLLING_TIMEOUT,  0,  set_poll_timeout_f lag) ; 

while  ((occ  =  GetBlockOccupancy(B))  ==  0C_FREE  ti  !poll_timeout_f lag) 
Sleep(POLLIHG_IirTERVAL) ; 


Figure  1.9:  demo.c,  an  example  using  tJie  ACI  (continued). 


25 


[E 


15 


16,17 


18 


iU 


il  {occ  ==  DC.ERROR)  { 

printi( "error  getting  block  occupancy !\n"); 
exit  (1); 

} 

if  (poll_timeout_flag)  { 

printf ("polling  timed  out  after  *Xf  secondsXn",  POLLIHG_TIHEQUT) ; 
exit  (1); 

> 

CancelTimerO ; 

/*  assertion:  occ  ==  OC.QCCUPIED  */ 

/* 

«  Perform  an  emergency  stop,  then  poll  until  train  stops 

•/ 

printf ("performing  emergency  stop\n"); 

EmergencyStop(T) ; 

printf ("polling  until  train  stops. . An"); 
poll_timeout_flag  =  0; 

lnit'Iimer(POLLISG_TIMEOTrr,  0,  set_poll_timeout_f lag) ; 

while  ((tm  =  GetTrainHotion(T))  ==  TM_M0VIHG  ftk  !poll_timeout_flag) 
Sleep(POLLIlIG.IirTERVAL) ; 

if  (tm  ==  TM_ERR0R)  < 

printf ("error  when  querying  about  train  motionlNn"); 
exit  (1); 

} 

if  (poll_timeout_flag)  { 

printf ("polling  timed  out  after  %f  secondsXn",  POLLIHG.TIMEOIT) ; 
exit  (1); 

> 

CancelTimerO ; 

/*  assertion:  tm  ==  TM.STQPPED  */ 
printf ("train  has  stopped. \n"); 
exit  (0); 

Figure  1.9:  demo.c,  an  example  using  the  ACI  (concluded). 
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The  example  program  demo.c  (see  Figure  1.9)  illustrates  the  use  of  the  ACT 
This  program  connects  to  a  simulation  and  receives  the  state  of  a  railroad,  then 
attempts  to  move  a  train  in  that  railroad  to  a  certain  block  and  perform  an 
emergency  stop.  Some  kev  points  about  the  code  are  indicated  by  numbers  ITl, 

[B  ' 

[T]  The  include  file  aci.h  conttuns  declarations  and  definitions  required  for 
compiling  a  source  file  that  uses  the  ACf.  In  order  to  create  an  executable, 
one  must  link  with  the  ACI  library  libaci.a. 

[T]  Time  values  passed  to  the  ACI  timer  procedures  are  always  floating-point 
quantities  representing  seconds.  An  ACI  type  Seconds  is  defined  for  such 
quantities. 

[T]  set_polling_timeout  is  the  procedure  that  will  be  invoked  if  a  tsuser 
timer  expires.®  Such  a  procedure  cannot  be  invoked  with  arguments,  so  it 
changes  a  global  variable  polling_timeout  in  order  to  inform  the  main 
program  about  timer  expiration. 


[T1  The  file  aci.h  defines  a  number  of  data  types  besides  LayoutData.  The 
type  TrainData  is  used  to  represent  download  information  received  for  a 
train;  likewise.  BlockData  represents  download  information  for  a  block. 
Both  TrainData  and  BlockData  are  component  types  used  in  the  defini¬ 
tion  of  LayoutData.  Enumerated  types,  including  Occupancy  and  Train- 
Motion,  are  used  for  command  arguments  and  query  return  values.  Trains 
and  blocks  have  unique  positive  integer  identifiers, 

[T|  GetDounload  takes  four  arguments,  returns  a  null  pointer  on  failure,  etc. 
Chapter  3  is  the  reference  for  this  and  the  other  ACI  procedures. 
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Several  examples  of  references  to  a  LayoutData  structure  follow'  the  invo¬ 
cation  of  GetDovnload.  More  direct  references  such  as 


datap->trains [T-l] . length 
datap->blocksCB-l] .t.rg.tail 


could  be  used  in  place  of  those  that  involve  tp  and  bp  in  deao .  c.  Observe 
that  the  index  of  a  train  in  datap->trains  is  always  one  less  than  that 
train’s  identifier.  A  similar  remark  holds  for  blocks. 

The  function  PrintDosnload  in  Appendix  B.2  includes  examples  of  refer¬ 
ences  to  every  component  in  a  LayoutData  structure. 

Checking  the  values  of  T  and  B  at  is  not  strictly  necessary  in  this 
program,  since  their  values  are  known  to  be  valid  in  this  case.  It  is  a 
good  defensive  programming  practice  to  include  such  checks  anyway,  as 
protection  against  future  changes. 

®Note:  As  explained  in  Section  3.6,  a  call  to  InltTinar  overrides  any  prior  calls.  Thus,  we 
speak  of  “the  ACI  timer,”  because  only  one  such  timer  can  be  in  effect  at  any  time. 
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ACI  commands  such  as  Accelerate  are  tton-falocking  and  return  no  vcdues. 
They  print  no  warnings  about  unresisonable  arguments.  The  command 

Accelerate(T,  20.0); 


requests  that  train  T  accelerate  for  a  duration  of  20  seconds,  increasing  its 
speed  during  that  period  at  the  predefined  fixed  acceleration. 
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The  instruction 


Sleep(2S.O); 


causes  demo.c  (not  the  Trainset  simulator!)  to  suspend  execution  for  25 
sec.  This  is  long  enough  that  the  subsequent  Decelerate  command  |  ii  | 
is  unlikely  to  interfere  with  the  prior  Accelerate  command  fe]. 

The  train  would  begin  to  reduce  its  speed  as  soon  as  the  Decelerate 
command  is  received,  even  if  the  prior  acceleration  had  not  been  in  effect 
for  the  acceleration’s  entire  duration.  For  example,  if  the  Sleep  had  been 
for  10  seconds  instead  of  25,  then  train  T  would  accelerate  for  about  10 
seconds,  then  decelerate  for  5  seconds. 


1 12  I  The  query  GetBlockDccupancy  is  used  so  that  train  T  may  reach  block 
B.  That  query  is  issued  frequently  until  block  B  is  found  to  be  occupied 
or  until  an  error  or  timeout  occurs.  This  technique  of  frequent  querying 
is  called  polling.  The  ACI  timer  is  set  up  before  the  Hhile  statement  to 
provide  timeout  mechanism  for  leaving  that  loop. 

1 13 1  The  loop  guard  condition  shows  that  there  are  two  ways  to  leave  the  loop. 


•  If  occ  differs  from  OC.FREE,  i.e.,  occ  has  veilue  0C_0CCUPIED  or 
0C_ERR0R,  then  the  loop  will  be  exited.  (Query  errors  can  be  caused 
by  invalid  arguments,  loss  of  communication  with  ‘4e  railroad,  etc.) 

•  If  polling_timeout  has  a  non-zero  vedue,  then  the  loop  will  be  ex¬ 
ited.  polling_tiBieout  changes  from  zero  to  a  non-zero  value  if  the 
timer  expires  (see  and  the  invocation  of  InitTimer). 
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Before  concluding  that  occ  =  0C_0CCUPIED,  which  would  indicate  occu¬ 
pancy  of  block  B,  it  is  necessary  to  eliminate  the  other  events  that  can 
cause  the  loop  to  exit. 


1 17 1  A  period  of  time  elapses  between  the  moment  that  block  B  becomes  oc¬ 
cupied  and  the  time  when  the  control  program  demo.c  can  act  on  that 
information.  This  time  period  arises  from  the  following  causes. 


•  Delay  from  polling.  Some  time  necessarily  elapses  between  the 
moment  that  block  B  becomes  occupied  and  the  time  when  that  sen¬ 
sor  is  checked.  The  sensor  is  checked  by  each  successful  call  to  the 
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query  GetBlockOccupancy.  Thus,  if  GetBlockOccupaacy  succeeds 
this  period  is  bounded  by  the  execution  time  of  one  iteration  of  the 
polling  loop,  except  possibly  when  block  B  is  found  to  be  occupied 
on  the  first  GetBlockOccupancy  query. 

•  Network  delay.  This  is  the  time  required  for  a  sensor  value  to  be 
communicated  to  the  control  program. 

•  Local  processing  delay.  Once  the  process  that  is  running  deno .  c 
receives  a  communication  that  block  B  was  occupied,  several  further 
steps  occur:  the  query  function  returns;  the  polling  loop  exits;  checks 
are  performed  in  order  to  deduce  that  block  occupancy  was  in  fact 
the  reason  for  loop  exit;  and  the  timer  is  cancelled.  Each  of  these 
steps  requires  loccii  processing  time. 

Such  delays  can  affect  the  correctness  of  control  programs.  For  example, 
the  occupancy  of  a  block  might  change  by  the  time  that  a  control  program 
could  take  action  on  that  occupancy  information.  In  particular,  it  is  not 
correct  to  conclude  that  block  B  is  currently  occupied  based  solely  on  the 
fact  that  occ  has  the  value  QC.,OCCUPIED  at  [  17 1. 

~i8]  The  command  EmergencyStop  causes  a  train  to  reduce  its  speed  to  zero 
quickly.  Unlike  Accelerate  and  Decelerate,  the  effects  of  EmergencyStop 
cannot  be  interrupted  by  another  command. 

li]  Polling  with  the  query  GetTrainMotion  is  used  in  demo.c  to  determine 
when  the  train  has  come  to  a  complete  stop. 

Exercises 

1.  Write  a  program  that  uses  the  ACI  to  cause  both  trains  in  the  sample 
layout  (see  Figure  1.1)  to  move  around  the  track  for  five  minutes,  then 
stop.  (Compare  to  Exercise  1  of  Section  1.1.2.)  The  trains  need  not  travel 
on  different  loops. 

2.  As  in  the  loop  1 12  |,  a  timer  is  set  up  just  before  the  while  statement  19 
in  order  to  guard  against  an  infinite  loop.  Is  this  timer  necessary,  or  is 
that  loop  certain  to  exit  in  a  reasonable  amount  of  time  without  a  timer? 
(Hint:  Consider  the  specifications  of  GetTrainMotion  in  Section  3.4.4.) 
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Chapter  2 

Trainset  Railroads 


2.1  Introduction 

Trainset  railroads  are  idealized  versions  of  real  railroads.  This  chapter  dis¬ 
cusses  the  attributes  and  operation  of  Trainset  railroads.  You  will  see  that 
while  Trainset  railroads  are  simpler  than  their  real-life  counterparts,  the  sim¬ 
plifications  are  ones  that  do  not  make  it  appreciably  easier  to  w'rite  programs 
to  control  the  railroad. 


2.2  Blocks 

In  a  Trainset  railroad,  a  layout  consists  of  an  assembly  of  blocks  together  wdth 
movable  trains  that  occupy  some  of  those  blocks.  See  Figure  1.1  for  an  example. 

Every  block  is  assigned  a  unique  block  ID  B,  a  length  Lg,  a  maximum  speed 
limit  MXg  and  a  minimum  speed  limit  MNg.  We  expect' 

0  <  MNg  <  MXg  <  MAX  FLOAT. 

Each  block  has  a  set  of  terminators  that  delimit  the  track  implementing  that 
block. 

As  in  real  railroads,  each  block  has  an  associated  sensor  called  a  track  circuit, 
that  indicates  whether  that  block  is  occupied  by  a  train.  Polling  a  track  circuit 
only  returns  one  bit  of  information  signifying  whether  the  associated  track  block 
is  occupied.  Note  that  it  is  not  possible  to  learn  the  exact  location  of  a  moving 
train  from  the  information  returned  by  a  track  circuit. 

A  block  may  have  between  two  and  four  terminators,  depending  on  its  type. 
There  are  five  types  of  train  blocks;  regular,  join,  switch,  cross  and  station 
blocks.  These  are  illustrated  in  Figures  2. 1-2.5. 

*  MA  XFL  OA  T  is  the  largest  floating  point  number  on  the  computer  system.  The  standard 
mk$  units  of  measure  are  used  throughout  this  document. 
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Figure  2.1:  Regular  Blocks 


Two  blocks  are  attached  to  each  other  if  each  of  the  blocks  has  a  terminator 
that  is  associated  with  the  other  block.  Trainset  block  layouts  are  subject  to 
the  following  restrictions. 

•  A  terminator  may  be  associated  with  at  most  one  block. 

•  A  block  may  not  be  attached  to  itself. 

•  Blocks  may  not  be  attached  to  each  other  more  than  once,  e.g.,  circular 
track  configurations  that  consist  only  of  two  half-circle  blocks  are  prohib¬ 
ited. 

These  restrictions  make  it  simpler  to  describe  attachments  between  blocks,  but 
do  not  limit  the  topology  of  Trainset  layouts.  For  example,  we  could  easily 
construct  a  circular  track  configuration  using  two  quarter  circles  and  a  semicir¬ 
cle. 

It  is  not  necessary  that  all  terminators  of  a  block  be  attached  to  other  blocks. 
Of  course,  a  train  will  derail  if  it  attempts  to  exit  from  a  block  at  an  unattached 
terminator. 

2.2.1  Regular  Blocks 

Each  regular  block  has  two  terminators.  Such  a  block  can  have  the  shape  of  a 
line  segment  or  a  circular  arc.  See  Figure  2.1. 

2.2.2  Join  Blocks 

A  join  block  has  three  terminators  and  allows  two  train  routes  to  merge.  Two 
of  the  terminators,  called  the  heads,  are  each  connected  to  the  third  terminator, 
called  the  tail. 

A  train  can  occupy  the  track  between  either  of  the  heads  and  the  tail.  l>ains 
can  enter  a  join  block  at  either  head  and  exit  through  the  tail.  A  train  derails 
when  it  either  enters  a  join  block  at  the  tail  or  leaves  from  one  of  the  heads. 
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Figure  2.2:  Join  Block 
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Figure  2.3;  Cross  Block 


Join  blocks  are  assumed  to  be  LENjoin  meters  long  measured  from  the  tail 
to  either  head  terminator.^  At  most  one  train  may  occupy  a  join  block  at  any 
time.  If  a  second  train  enters  a  join  block  that  is  already  occupied,  then  a 
collision  occurs. 

2.2.3  Cross  Blocks 

A  cross  block  (see  Figure  2.3)  allows  a  track  to  intersect  itself,  so  that  “figure 
eights”  and  related  designs  may  be  built.  A  cross  has  four  terminators,  and  a 
train  may  only  travel  between  any  opposing  pair — turns  are  not  allowed.  Thus, 
cross  blocks  behave  like  two  short  regular  blocks,  called  subblocks,  with  the 

^Constants  such  as  are  determined  at  the  time  of  installation.  Sec  the  installation 

mzinual  for  details. 
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Figure  2.4:  Switch  Block 


same  length  and  speed  limits,  that  have  been  oveilaid  at  their  midpoints.  A 
cross  block  and  both  of  its  subblocks  are  occupied  whenever  either  of  those 
subblocks  is  occupied.  Cross  subbiocks  are  LENcross  Jneters  long.  A  collision 
occurs  when  a  cross  block  becomes  occupied  by  two  or  more  trains. 

In  order  to  distinguish  between  the  subbiocks  of  a  cross  block,  each  has  its 
own  block  ID.  One  of  these  also  serves  as  the  cross  block’s  ID. 


2.2.4  Switch  Blocks 

A  switch  block  (see  Figure  2.4)  has  three  terminators,  labelled  tail,  straight  head 
and  turn  head,  and  consists  of  a  movable  track  segment  that  has  two  settings 
and  a  mechanism  to  move  this  track  between  those  settings.  Depending  on  the 
setting  of  the  movable  track,  either  the  train  may  travel  between  the  tail  and 
straight  head  (in  either  direction)  or  between  the  tail  and  turn  head.  Thus,  a 
switch  block  can  be  part  of  two  different  train  routes,  according  to  that  switch 
block’s  setting. 

A  switching  time  Tg^jtcb  must  elapse  for  a  switch  block  to  change  from  one 
setting  to  the  other.  The  switch  setting  is  undefined  during  this  time  period. 
If  a  svitch  is  commanded  to  change  to  one  setting  (e.g.,  straight)  while  it  is 
already  in  that  setting  or  in  the  process  of  changing  to  that  setting,  then  that 
setting-change  command  has  no  effect.  If  the  setting-change  command  was  to 
switch  to  the  ofAer  setting,  then  the  switch  begins  changing  to  the  new  setting. 
It  takes  a  full  Tgy^ifch  seconds  to  change  to  a  new  setting,  even  if  the  switch 


Figure  ‘2.0'  Slaiiou  Block 

setting  was  undefined  at  the  time  of  the  setting  change  command. 

A  train  attempting  to  traverse  a  switch  block  will  derail  under  the  following 
circumstances. 

•  The  switch  block  has  undefined  setting. 

•  A  switch  change  is  attempted  on  the  switch  block. 

•  The  train  enters  the  turn  head  terminator  of  a  straight  switch,  or  the 
straight  head  terminator  of  a  turned  stvitch. 

Switch  blocks  are  hfA'sH'/tch  meters  long  measured  from  the  tail  to  either  of 
the  other  terminators.  At  most  one  train  may  occupy  a  switch  block  at  a  time 
or  a  collision  will  occur. 

A  switch  block  that  is  occupied  by  a  derailed  or  collided  train  will  not  respond 
to  setting  change  commands. 

2.2.5  Station  Blocks 

Station  blocks  are  like  regular  blocks  (see  Figure  21)  except  that  they  allow  a 
train  to  stop  at  a  fixed  specified  location.  Using  a  station  block  is  the  only  way 
to  be  sure  of  the  exact  position  of  a  train  after  it  ha.s  begun  moving,  because 
track  circuits  only  reveal  whether  a  block  was  occupied  .sometime  in  the  pa.st. 

Each  station  block  B  has  a  station-stop-speed  VSS^^.  A  station  stop  begins 
whenever  a  train  that  is  in  station-stop  mode  (see  Section  2.3)  enters  a  station 
block  while  travelling  wdth  speed  at  most  VSS^.  Under  these  conditions,  the 
train  will  automatically  begin  to  slow  down  so  that  it  wall  come  to  a  complete 
stop  exactly  at  the  opposite  terminator  of  the  station  block. 

A  station  stop  by  a  train  can  be  aborted  by  commanding  that  train  to  change 
velocity  or  acceleration. 
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Figure  2.6:  Block  occupancy. 

2.3  Trains 

Every  train  is  assigned  a  unique  train  ID  r  and  a  length  and  has  the  following 
attributes  that  may  change  during  a  simulation. 

•  A  speed  Vj.  and  an  acceleration  a^. 

•  Two  ends,  labelled  head  and  tail,  that  are  points  within  blocks. 

•  A  direction  dir^. 

•  An  emergency-stop  mode  es^  and  a.  station-stop  mode  ss^.  v  .  h  may  be 
enabled  or  disabled. 

VVe  expect  0  <  Vj.  <  MAXFLOAT.  The  distance  along  the  track  between  a 
tram’s  ends  is  always  that  train’s  length  L^. 

Each  train  in  a  layout  always  occupies  a  sequence  of  attached  blocks.  A 
train  occupies  a  block  if  the  interiors  of  that  train  and  that  block  intersect.  For 
example,  suppose  that  the  train  in  Figure  2.6  has  just  completed  a  station  stop, 
so  that  one  end  of  that  train  is  at  a  terminator.  That  train  occupies  blocks 
rg  10  and  st  11,  but  does  not  occupy  block  rg  12.  If  that  tram  moves  slightly 
to  the  left  (i.e.,  foiward),  it  will  then  occupy  block  xg  12. 

A  train’s  direction  dir^  determines  which  of  the  two  ends  advances  if  that 
train  moves  forward.  The  treiin  end  that  advances  is  called  the  front,  and  the 
other  end  is  called  the  rear.  For  example,  suppose  that  the  head  of  a  train  is 
the  front.  If  that  train’s  direction  is  changed,  then  the  train's  tail  will  become 
the  front  and  the  head  will  become  the  rear.  A  train’s  direction  can  only  change 
w'hen  that  train  is  not  moving,  that  is,  when  =  a,.  =  0. 

2.3.1  Train  States 

A  train  can  be  in  one  of  three  states:  operational,  derailed  or  collided.  Figure  2.7 
shows  possible  transitions  between  these  states. 

A  train’s  state  changes  from  operational  to  derailed  under  any  of  the  follow¬ 
ing  conditions: 
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Figure  2.7:  Train  state  transitions. 


•  That  train  occupies  a  block  and  the  train's  speed  violates  one  of  that 

block’s  speed  limits,  or  A/A'^  <  ty. 

•  The  front  of  that  train  exits  a  block  at  an  unattached  terminator. 

•  The  front  of  that  train  enters  a  join  block  at  the  tail  terminator  or  exits 
a  join  block  from  a  head  terminator. 

•  That  train  occupies  a  switch  block  that  has  undr  .ned  setting. 

•  A  switch  change  is  attempted  on  a  switch  block  occupied  by  that  train. 

•  That  train  enters  the  turn  head  terminator  of  a  switch  in  the  straight 
setting  or  the  straight  head  terminator  of  a  switch  in  the  turned  setting. 

A  train’s  state  changes  to  collided  if  there  is  another  train  in  the  layout  such 
that  either  of  the  following  conditions  holds. 

•  Both  trains  occupy  the  same  switch,  join  or  cross  block. 

•  Both  trains  occupy  the  same  block  at  the  same  point. 

2.3.2  Laws  of  Motion 

In  Trainset,  the  acceleration  of  a  train  is  one  of  the  constant  values  ACC,  0, 
—ACC  and  —Aemer-  except  during  a  station  stop.  We  expect 

0  <  ACC<  Aemer  <  MAX  FLO  AT. 

If  the  acceleration  cLj.  of  a  train  is  constant  during  a  time  interval  [<oTi]  and 
v(ti)  is  the  speed  Vj.  of  that  train  at  time  ti,  then 

=  t;(<o)  +  Or  •  -  <n)- 
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For  such  a  train,  if  represents  the  position  of  an  end  of  that  train  at  tune 
then 

=  j;(<o)  4-  t(iu)  •  (<i  ~  <o)  +  -^  m  ~  Ui)‘ 

A  train's  station-stop  mode  turns  on  the  station-slop  feature  for  that  train. 
A  station  stop  begins  if  the  station-stop  mode  of  a  train  is  enabled  and  that 
train  enters  a  station  block  with  speed  v.^  satisfying 

0  <  <  VSS^. 

where  VSS^  is  the  station-stop  speed  of  that  block.  The  station-stop  mode  of 
that  train  is  disabled  as  soon  as  a  station  stop  begins, 

A  station  stop  by  a  train  can  be  aborted  by  setting  that  train's  speed  or 
acceleration  during  that  station  stop,  ff  a  train  performs  a  station  slop  in  a 
station  block  and  that  station  stop  is  not  aborted,  then  all  of  the  following  will 
hold  upon  its  completion. 

•  The  train’s  speed  v^.  and  acceleration  o^.  will  be  0. 

•  The  train’s  front  will  be  at  the  opposite  terminator  of  that  station  block. 

•  The  train  will  occupy  that  station  block. 

A  station  stop’s  completion  may  be  observed  using  the  query  GetTrainMotion 
discussed  in  Section  3-4. 

The  emergency-stop  feature  allows  a  train  to  stop  at  a  faster  rate  than 
usual.  A  train  performs  an  emergency  stop  when  its  emergency-stop  mode 
is  enabled.  During  an  emergency  stop  by  a  train  T.  its  acceleration  satisfies 
a-r  =  —Aemer-  The  emergency  stop  finishes  as  soon  as  v-j.  becomes  0.  At  that 
time,  the  emergency-stop  mode  for  Tis  disabled  and  its  acceleration  becomes 
0. 

A  train  does  not  respond  to  commands  during  an  emergency  stop.  Thus, 
emergency  stops  cannot  be  aborted. 
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Chapter  3 


Automatic  Control 
Interface  (ACI) 


3.1  Introduction 

The  Control  Program  Interface  (CPI)  is  used  for  writing  computer  programs 
that  interact  with  Trainset  railroads.  It  consists  of  two  layers,  the  Automated 
Control  Interface  (ACI)  and  the  Low-Level  Interface  (LLI),  as  illustrated  in 
Figure  3.1. 

The  ACI  layer  consists  of  library  routines  that  can  be  used  in  a  control 
program  to  establish  communication  w'ith  a  simulation  of  a  Trainset  railroad, 
obtain  the  state  of  that  railroad,  interact  with  the  railroad’s  layout  using  com¬ 
mands  and  queries  and  use  the  Trainset  voting  service.’  The  ACI  also  provides 
some  locd  timer  utilities.  This  layer  is  intended  to  meet  the  needs  of  most  con¬ 
trol  program  w'riters. 

'The  voting  service  facilitates  writing  fault-tolerant  control  programs.  See  Section  3.5. 
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Figure  3.1:  Communication  interface  layers. 
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The  LLI  layer  has  most  of  the  same  capabilities  as  the  ACl,  but  at  a  more 
primitive  level  that  requires  a  programmer  to  manage  communication  and  mes¬ 
sage  buffers  directly. 

This  chapter  describes  the  ACl  layer.  Usage  details  are  described  in  a  ref¬ 
erence  formal  using  C  language  syntax.  Chapter  4  presents  the  LLI  layer. 
For  programming  examples  that  use  the  ACl  layer,  see  Section  1.4  and  Ap¬ 
pendix  B.2. 

A  Trainset  rciilroad  can  accept  three  kinds  of  messages  from  CPI  clients. 
A  stale  download  request  asks  for  a  railroad’s  state.  A  command  can  affect  a 
railroad  layout,  e.g.,  by  changing  a  switch  block’s  setting  or  setting  a  train's 
acceleration.  A  query  requests  information  about  a  block  or  train. 

Trainset  railroads  silently  ignore  messages  that  contain  syntax  errors. 

3.2  Initial-State  Download 

LayoutData  * 

GetDoBnloadfhostname,  simnvun,  prognane,  timeout) 

char  *hostname;  /*  machine  running  a  simulation  */ 
int  simnum;  /*  identifies  a  running  simulation  */ 
char  •progname;  /♦  name  of  invoking  program  */ 
double  timeout;  /*  in  seconds  */ 

Executing  GetDownload  causes  a  network  connection  to  be  established  with 
a  railroad  simulation  and  information  about  the  state  of  the  railroad  to  be 
received  from  that  simulation.  The  download  is  stored  in  an  internal  static  data 
structure  of  type  LayoutData  defined  in  Appendix  B.  1 . 

hostname  and  simnum^  must  identify  an  executing  Trainset  railroad  simu¬ 
lation,  and  timeout  must  be  positive,  or  GetDownload  will  fail.  If  hostname  is 
an  empty  string,  then  the  local  host  is  used. 

The  address  of  the  LayoutData  structure  is  returned  if  execution  succeeds. 
A  message  is  printed  and  a  NULL  pointer  is  returned  on  failure.  Possible  failure 
conditions  are; 

•  timeout  is  not  a  positive  floating-point  value. 

•  A  network  connection  could  not  be  established  before  timeout  seconds 
elapsed. 

•  There  is  no  simulation  on  the  host  hostname  with  identifier  simnum, 

^simnum  determines  which  well-known  ports  are  to  be  used  when  initi2dizmgconununication 
with  a  railroad  simulation.  Multiple  railroad  simulations  may  be  run  simultaneously  on  the 
same  host  if  they  use  different  simnum  values. 
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•  An  error  was  detected  while  parsing  the  download. 

•  GetDownload  has  already  been  called  successfully  by  this  client  at  a  prior 
time. 

The  download  consists  of  the  following. 

General  parameters: 

•  The  number  of  blocks  N^iocks  ®^nd  of  trains  A’trains  layout.  Block 

IDs  range  from  1  to  Nblocks  and  train  IDs  range  from  1  to  A'trains 

•  The  standard  acceleration  rate  ACC  And  emergency-stop  acceleration  rate 
Aemer  for  trains. 

•  The  switching  time  TsyrUch  f°*'  switch  blocks. 

•  The  voting  w'indow  W^otiag  and  voting  quorum  Qvotiag  f®*"  commands  to 
be  accepted.  See  Section  3.5. 

For  each  block: 

•  The  ID  B,  type  and  length  of  the  block. 

•  The  maximum  speed  limit  and  minimum  speed  limit  M.\’g 

•  The  attachments  for  that  block.  A  block  ID  is  specified  for  each  attached 
terminator  and  0  for  each  unattached  terminator. 

•  For  station  blocks,  the  station-stop  speed  VSS^ . 

•  For  subblocks  of  cross  blocks,  the  block  ID  of  the  cross  block. 

For  each  train: 

•  The  ID  T  and  length  of  that  train. 

•  The  locations  of  that  train’s  head  and  tail  ends.  The  location  of  an  end 
of  a  train  is  specified  by  giving  the  ID  of  a  block  containing  that  end  and 
the  offset  of  that  end  within  the  block.  Offsets  are  measured  from  the  tail 
terminator  of  a  block. 

3.3  Commands 

A  CPI  client  can  cause  a  change  in  a  Traiaset  railroad  by  issuing  a  command. 

Such  a  change  is  cedled  a  layout  action.  Only  trains  and  switch  blocks  can  be 

affected  by  commands. 
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Each  command  gives  rise  to  at  most  one  layout  action.  A  command  fails 
to  cause  a  layout  action  if  the  preconditions  of  that  command  are  not  satisfied. 
For  example,  a  SetDirection  command  causes  a  new  direction  to  be  assigned 
to  a  train  only  if  that  train  is  operational  and  not  moving.  Also,  multiple  com¬ 
mands  may  optionally  be  required  to  cause  a  single  layout  action,  as  described 
in  Section  3.5. 

There  are  seven  types  of  command  that  a  CPI  client  can  send  to  aTrainset 
railroad;  SetSwitch.  Accelerate,  Decelerate.  SetSpeed,  SetDirection, 
EmergencyStop  and  StationStop.  These  are  specified  as  follows. 

3.3.1  Set  Switch 

enum  HesPosit  -CKP.STRAIGHT,  SP.TURHED}; 
void 

SetSwitchfblock.id,  neti_setting) 
int  block. id; 

enum  HeuPosit  nes.setting; 

SetSwitch  causes  the  switch  block  identified  by  block.id  to  begin  changing 
setting  to  new.setting.  A  setting  change  requires  Tswitct  seconds  to  complete. 

block.id  must  identify  an  unoccupied  switch  block  that  is  neither  in  the 
setting  new.setting  nor  in  the  process  of  changing  to  that  setting;  otherwise 
no  action  is  taken. 

3.3.2  Accelerate  and  Decelerate 

void 

Accelerate(train_id,  duration) 
int  train. id; 
double  duration; 


void 

Decelerateftrain.id,  duration) 
int  train.id; 
double  duration; 


Accelerate  and  Decelerate  cause  the  acceleration  fltrain.id  of  the  train 
identified  by  train.id  to  be  assigned  the  following  value. 


^Hrain.id 


+ACC 

-ACC 


for  Accelerate 
for  Decelerate 
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“train  id  assigned  the  value  0  after  either  di  ion  seconds  elapse  or  the 
train’s  speed  reaches  0,  whichever  comes  first,  unless  atrain.id*®  changed  again 
or  the  train  collides  or  derails. 

duration  must  be  non-negative,  and  train_id  must  identify  an  operational 
train  that  is  not  performing  an  emergency  stop;  otherwise  no  action  is  taken. 

3.3.3  Set  Speed 


void 

SetSpeed(train_id,  goal.speed) 
int  train. id; 
double  goal.speed; 

SetSpeed  causes  the  acceleration  “train.idofthe  train  identified  by  train.id 
to  be  assigned  the  following  value. 

{+ACC  if  goal.speed  >  t>train.id 
0  if  goal.speed  =  t^rain.id 

-ACC  if  goal.speed  <  t'train.id 

The  acceleration  “train.id  's  assigned  the  value  0  when  that  trtun’s  speed 
reaches  goal.speed.  unless  “train.id  is  changed  again  or  the  train  derails  or 
collides  before  the  goal  speed  can  be  reached. 

goal.speed  must  be  non-negative,  and  train.id  must  identify  an  opera¬ 
tional  train  that  is  not  performing  an  emergency  stop;  otherwise  no  action  is 
taken. 

3.3.4  Set  Direction 

void 

SetDirection(train_id,  nev.dir) 
int  train.id; 
int  nev.dir; 

SetDirect ion  causes  the  direction  train  identified  by  train.id 

to  be  assigned  the  following  vdue. 

itail-to-head  if  new.dir  >  0 

head-to-tail  if  new.dir  <  0 

opposite  of  dirtrain.id  if  new.dir  =  0 

Here,  iail-to-head  means  that  the  head  end  of  that  train  is  the  front  end,  and 
kead-to-tail  means  that  the  tail  end  is  the  front  end. 
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The  direction  dn'train.id  of  train_id  must  identify  an  operational  train 
that  satisfies 

<*train_id  =  ^train.id  —  0 

or  no  action  is  taken. 

3.3.5  Emergency  Stop 


void 

EniergeiicyStop(train_id) 
int  train_id: 

EmergancyStop  causes  the  emergency-slop  mode  estrain.id  of  the  train 
identified  by  train_id  to  be  enabled.  This  causes  an  emergency  stop  to  begin 
immediately.  That  train’s  acceleration  otrain  id  assigned  the  value  —Aemer 
until  the  train's  speed  retrain  id  becomes  0,  at  which  time  a^rain  id‘®  assigned 
the  value  0  and  estrain.id  is  disabled. 

train.id  must  identify  an  operational  train,  or  no  action  is  taken. 

3.3.6  Station  Stop 


enum  StationStopMode  {SS.DISABLED,  SS.ENABLED}; 
void 

StationStop(train_id,  new.val) 
int  train. id; 

enum  StationStopMode  nes.val; 

StationStop  causes  the  station-stop  mode  sstrain  id  of  the  train  identified 
by  train_id  to  be  assigned  neu.val.  A  station  stop  (see  Section  2.3.2)  begins 
if  an  operationeil  train  enters  a  station  block  with  station-stop  mode  enabled 
and  with  speed  Strain  id  that  does  not  exceed  the  block’s  station-stop  speed 
VSS^. 

train.id  must  identify  an  operational  train  that  is  not  performing  an  emer¬ 
gency  stop;  otherwise  no  action  is  taken. 


3.4  Queries 

Queries  are  the  only  way  that  a  CPI  client  can  obtain  information  about  a 
layout  after  the  initial-state  download  has  been  received.  There  are  four  query 
types;  GetBlockOccupancy , GetSaitchPosition.  GetTrainStatus  and 
GetTraiuMotion.  These  queries  return  very  limited  information.  Thus,  facts 
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about  the  layout's  state  such  as  a  train’s  speed  and  emergency-stop  mode  must 
be  computed  by  a  C1*I  client  program  from  a  knowledge  of  past  values  and  of  the 
properties  of  Trainset  railroads.  This  makes  writing  process  control  programs 
difficult  but  reedistic- 

3.4.1  Block  Occupancy 

enuiB  Occupancy  {OC.FREE,  OC_OCCUPIED,  OC_ERROK  =  -!>; 

enum  Occupancy 
GetBlockQccupancy(block_id) 
int  block_id; 

The  occupancy  status  of  the  indicated  block  is  returned.  If  block.id  is  not 
the  ID  of  a  block  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation. 
OC_ERRQR  is  returned. 

3.4.2  Switch  Position 

enum  SwitchPosit  {SP.STRAIGHT,  SP.TURHED,  SP.UHDEFIBED, 
SP.ERROR  =  -1>: 


enum  SwitchPosit 
GetSwitchPosition(block_id) 
int  block_id; 

The  setting  of  the  indicated  switch  block  is  returned.  If  block.id  is  not  the 
ID  of  a  switch  block  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation, 
SP_ERR0R  is  returned. 

3.4.3  Train  Status 

enum  TrainStatus  {TS_CRASHED,  TS_RUHNIHG,  TS_ERR0R  =  -1}; 

enum  TrainStatus 
GetTrainStatus (train. id) 
int  train.id; 

If  the  indicated  train  has  state  operationcd.  TS.RUHNING  is  returned.  If  that 
train’s  state  is  derailed  or  collided,  TS.CRASHED  is  returned.  If  train.id  is  not 
the  ID  of  a  train  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simulation, 
TS.ERROR  is  returned. 
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3.4.4  Train  Motion 


enum  TrainMotion  {TH.STOPPED,  TH.MQVING,  TM.ERROR  =  -1>: 

enujn  TrainMotion 
GetTrainMot i on ( tr ain_ id) 
int  train. id; 

If  the  indicated  train  has  state  operational  and  at  least  one  of  the  train’s 
speed  i>train_id  or  acceleration  fltrain.id  is  non-zero,  TM.HOVIRG  is  returned. 
Otherwise,  TM.STOPPED  is  returned,  except  that  TM.ERRQR  is  returned  if  train.id 
is  not  the  ID  of  a  train  or  if  a  timeout  occurs  awaiting  a  reply  from  the  simula¬ 
tion. 


3.5  Voting 

The  voting  service  supports  the  writing  of  fault-tolerant  control  programs  for  a 
Trainset  railroad.  By  default,  there  is  a  one-to-one  relationship  between  CPI 
client  commands  (satisfying  various  preconditions,  as  described  in  Section  3.3) 
and  layout  actions.  The  voting  service  makes  it  possible  to  require  that  a  simu¬ 
lation  receive  a  specified  number  CPI  clients 

within  a  certain  time  period  Wvoting  before  a  layout  action  can  occur. 

The  behavior  of  the  voting  service  is  governed  by  the  following  parameters. 

•  A  voting  quorum  Qvotiag  (integer).  When  the  voting  service  is  being 
employed,  a  layout  action  can  be  generated  only  if  Quoting  commands 
satisfying  the  conditions  below  are  received  from  different  CPI  clients. 

•  A  voting  window  ITvonug  (floating  point,  seconds).  This  is  a  time  limit  af¬ 
ter  which  CPI  client  commands  expire.  If  a  command  has  not  contributed 
to  a  layout  action  within  Wyotiag  seconds  after  receipt  by  a  simulation, 
then  that  command  will  have  no  effect. 

•  A  sequence  number  seq  (integer)  that  is  associated  with  each  CPI  com¬ 
mand. 

We  expect  Qvotiag  >  voting  >  0  and  seq  >  0. 

The  voting  service  is  enabled  only  for  commands  with  positive  sequence 
numbers.  Figuratively  speaking,  commands  with  different  positive  sequence 
numbers  participate  in  different  “elections.” 

The  following  paragraphs  provide  a  specification  of  the  voting  service. 

Sequence  number  0,  If  a  command  has  sequence  number  0,  then  that  com¬ 
mand  alone  generates  a  layout  action  immediately,  as  described  in  Section  3.3. 
The  values  of  Wyotiag  and  Qvotiag  no  effect  on  such  commands. 
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lime 

command 

type 

client 

sequence 

number 

Command  A 

7:22:06 

Accel 

2 

61 

B 

7:22:13 

Accel 

1 

60 

C 

7:22:17 

Accel 

3 

61 

D 

7:22:19 

Accel 

1 

60 

E 

7:22:25 

SetSpeed 

2 

61 

F 

7:22:30 

SetSpeed 

3 

61 

Figure  3.2;  Voting  example  (positive  sequence  numbers). 


Positive  sequence  numbers.  If  a  simulation  receives  Quoting  more  com¬ 
mands  with  the  same  positive  sequence  number  seq  from  different  CPI  clients 
during  any  time  period  of  Wyoming  seconds  or  less,  then  a  single  layout  action  is 
generated.  By  default,  the  layout  action  generated  is  the  action  caused  (subject 
to  the  preconditions  listed  in  Section  3.3)  by  the  last  of  those  commands. 

No  commands  with  positive  sequence  numbers  can  otherwise  contribute  to 
layout  actions.  Commands  with  the  same  sequence  number  need  not  have  the 
same  arguments  nor  even  the  same  command  type.  A  command  can  contribute 
to  the  generation  of  at  most  one  layout  action. 

For  example,  suppose  that  VF voting  =  10  sec,  Qyotiag  -  2  and  that  the 
commands  in  Figure  3.2  are  received  by  a  simulation.  Then  only  one  layout 
action  will  be  performed  by  that  simulation  as  of  the  time  7:22:30.  That  layout 
action  will  be  E,  occurring  at  time  7:22:25.  The  quorum  of  commands  consists 
of  C  and  E. 

The  values  of  Qyotiag  and  H'vot/ngare  determined  when  a  Trainset  railroad 
simulation  is  invoked,  and  cannot  be  changed  during  a  simulation.  The  default 
value  for  Qyotiag  2,  and  the  default  value  for  Wyotiag  is  5  seconds. 

Sequence  numbers  can  be  modified  dynamically  by  a  control  program.  The 
ACI  provides  an  interned  sequence-number  variable  seq^cj  whose  value  is  auto¬ 
matically  sent  with  each  command.  The  value  of  the  variable  remains 

constant  unless  explicitly  modified,  and  the  initial  value  is  0. 

In  order  to  employ  the  voting  service,  it  is  necessary  to  start  a  simulation 
with  Qyotiag  >  1  ®nd  to  send  commands  that  have  positive  sequence  numbers. 
The  ACI  provides  two  functions  for  modifying  the  value  of  a  sequence  number. 
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3.5.1  New  Sequence  Number 


int 

SeHSeqKtunberO 

The  sequence  number  is  incremented  and  the  new  value  is  returned. 

3.5.2  Set  Sequence  Number 

int 

SetSeqNumber(neB_val) 
int  neH_val; 

If  new.val  is  non-negative,  the  sequence  number  stg  is  eissigned  new_val. 
and  that  value  is  returned.  Otherwise,  se.g  is  left  unchanged  and  -1  is  returned. 


3.6  Timer  Facilities 

The  ACI  layer  provides  procedures  that  implement  a  simple  timer  service  in 
which  time  quantities  are  represented  p,s  seconds  in  floating  point.  These  rou¬ 
tines  alfect  a  program  that  calls  them;  they  do  not  themselves  interact  with 
a  Trains et  railroad.  Alternative  time-management  routines  or  direct  system 
calls  may  be  used  instead  of  these  timer  procedures  when  writing  programs  that 
use  the  ACI.  Thus,  use  of  the  ACI  timer  facilities  is  optional. 

The  five  timer  procedures  are  InitTimer.  GetTimer.  ARaitTimer,  Cancel- 
Timer  and  Sleep. 

3.6.1  Initialize  Timer 

enum  TiraerRetum  <TMR_SUCCESS,  THR_ERRQR  =  -1}; 
typedef  double  Seconds; 

enum  TimerReturn 
InitTimer (first,  period,  f) 

Seconds  first;  /*  delay  to  first  timeout  ♦/ 

Seconds  period;  /♦  wait  between  successive  timeouts  */ 
void  (♦f)();  /*  function  executed  upon  each  timeout  */ 

InitTimer  initializes  the  timer  mechanism  to  execute  the  function  f  ()  after 
first  second,s  and  every  period  seconds  thereafter.  If  first  i.s  zero,  the  timer 
is  immediately  disalled.  If  period  is  zero,  the  timer  executes  f  ()  at  most  once. 
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If  the  value  zero  is  specified  instead  of  a  function  f .  theti  nothing  is  done  on 
timeouts  except  to  reset  the  timer  as  appropriate.  THR_SUCCESS  is  returned 
if  the  operation  succeeds.  If  a  time  argument  is  negative  or  a  low-level  error 
occurs.  TMR_ERROR  is  returned. 

A  call  to  InitTimer  overrides  any  prior  timer  .setting.  Thus,  there  is  no 
provision  for  more  than  one  timer  being  in  effect  at  any  time.  The  timers  u.sed 
in  other  ACI  functions,  including  GetDoHnload.  the  ACl  queries  and  Sleep,  do 
not  interfere  with  InitTimer. 

3.6.2  Get  Timer  Values 

enum  TimerStatus  fTHS.DISABLED,  TMS.OHCE,  TMS.INDEFINITE, 
TMS.ERROR  =  -1}; 
typedef  double  Seconds; 

enum  TimerStatus 
GetTimerCnextp,  periodp) 

Seconds  *neitp;  /•  next  scheduled  timeout  */ 

Seconds  *peTiodp;  /*  delay  between  successive  timeouts  */ 

GetTimer  stores  the  seconds  remaining  until  the  next  timer  expiration  in 
♦nextp  and  stores  the  current  period  between  timer  expirations  in  *periodp. 
The  return  value  is  TMS.DISABLED  if  the  timer  is  currently  disabled.  TMS_ONCE 
if  the  timer  is  scheduled  to  expire  once  only,  TMS.ISDEFIHITE  if  the  timer  is 
scheduled  to  continue  indefinitely  and  TMS.ERROR  if  a  low-level  error  occurs. 

3.6.3  Await  for  Timer 


void 

AwaitTimerO 

AwaitTimer  suspends  the  calling  process  until  an  ACI  timer  expiration  or 
another  operating  system  signal  occurs. 

3.6.4  Cancel  Timer 

enum  TimerReturn  {THR_SUCCESS,  TMR.ERROR  =  -l}; 

enum  TimerReturn 
CancelTimerO 
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CancelTiner  caiiceb  an  ACJ  timer.  TMR_SUCCESS  is  returned  if  llie  oper¬ 
ation  succeeds.  CancelTimer  fails  if  a  low-level  error  occurs,  in  which  case 
THR_ERR0R  is  returned. 

3.6.5  Sleep 

enum  TimerReturn  {TMR_SUCCESS ,  TMR.ERROR  =  -1>; 
typedef  double  Seconds; 

enum  TimerReturn 
Sleep(sec) 

Seconds  sec;  /♦  maix  number  of  seconds  to  suspend  */ 

Sleep  suspends  the  calling  process  for  indicated  number  of  seconds.  The 
value  TMR_SUCCESS  is  returned  if  the  suspension  was  not  interrupted  before  the 
time  limit  expired.  Otherwise,  TMR_ERROR  is  returned. 

Sleep  does  not  interfere  with  the  operation  of  InitTimer.  Thus,  these 
functions  may  be  used  together,  e.g.,  to  set  up  a  polling  loop  with  a  timeout. 
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Chapter  4 


Low-Level  Interface  (LLI) 


4.1  Introduction 

The  Low-Level  Interface  (LLI)  consists  of  predefined  message  formats  and  re¬ 
lated  facilities  for  communicating  with  a  Trainset  railroad  simulation.  This 
layer  is  used  to  implem(nt  the  ACI  layer  in  the  Control  Program  Interface  (see 
Figure  3.1). 

This  chapter  gives  a  sketch  of  the  LLI  layer.  A  reading  knowledge  of  the 
C  programming  language  is  assumed.  The  rest  of  this  chapter  includes  the 
following  sections. 

•  Section  4.2  is  external  documentation  for  the  source  file  cpi.h  (see  Ap¬ 
pendix  C.  1 ).  The  internal  structure  of  that  file  is  described,  and  the  source 
lines  that  pertain  to  the  acceleration  command  are  discussed  as  examples. 

•  Section  4.3  describes  the  steps  necessary  for  a  client  to  connect  and  identify 
itself  to  a  Trainset  reiilroad  simulation. 

•  Sections  4.4  and  4.5  briefly  list  the  message  formats  that  are  used  for 
initial-state  downloads,  commands  and  queries.  A  knowledge  of  the  ACI 
layer  (Chapter  3)  is  assumed. 

For  a  programming  example  that  uses  the  LLI  programming  layer,  see  the 
implementation  of  the  ACI  layer  in  the  source  file  aci.  c  (Appendix  C.2). 


4.2  Messages 

In  the  LLI  layer,  a  control  program  interacts  with  a  Trainset  railroad  simula¬ 
tion  by  sending  and  receiving  messages.  An  LLI  message  is  an  ASCII  character 
string  that  is  organized  according  to  one  of  the  message  formats  defined  in 
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Q 

#define  MSG_CPI_ACCEL  "Xa*/.d,*/.d:%d:y.lf#" 
typedef  struct  {. 

int  client_id;  /*  unique  identifier  for  this  client  */ 

' — I  int  seq_num;  /*  label  for  this  command  */ 

int  train.id;  /*  simulator  train  number  */ 
double  duration;  /*  time  to  accelerate  in  seconds  ♦/ 

>  MsgCPIAccel; 

#define  MSG.CPI.ACCEL.ARGC  4 

tdefine  MsgCPIAccelArgsCbuff ,  datap)  (buff,  MSG_CPI_ACCEL,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->duration  ) 

0 

#define  CreateMsgCPIAcceKbuff ,  datap)  sprintf  MsgCPIAccelArgsCbuff,  (datap)) 
|T|  #define  ParseMsgCPIAccel(buff ,  datap)  sscanf  MsgCPIAccelArgsCbuff,  A(datap)) 


Figure  4.1:  Excerpt  from  cpi.h  relating  to  acceleration  command. 


cpi.h.  Each  such  message  format  consists  of  fields  for  representing  data,  to¬ 
gether  with  an  identifying  header  and  delimiter  characters. 

For  example,  consider  Figure  4.1,  an  excerpt  from  cpi.h.  Line  Q]  defines  a 
message  format  called  HSG_CPI_ACCEL.  That  message  format  has  the  following 
syntax. 

Xa  (integer)  ,  {integer)  :  (integer)  :  (float)  # 

There  are  four  fields.  The  notations  (integer)  and  (float)  indicate  ASCII  repre¬ 
sentations  of  integer  and  floating  point  numbers.  The  lota!  length  of  a  message 
depends  on  the  lengths  of  the  data  in  its  fields. 

In  general,  for  each  message  format  in  cpi.h  there  is  a  type  definition  of 
an  associated  data  structure  whose  components  correspond  to  the  fields  of  that 
message  format,  in  the  same  order.*  For  MCG.CPI.ACCEL.  the  associated  data 
structure  is  called  MsgCPIAccel.  See  the  lines  near  in  Figure  4.1. 

A  comparison  of  the  message  format  MSG_CPI_ACCEL  and  the  documented 
data  structure  MsgCPIAccel  shows  that  the  first  (integer)  field  in  that  message 
format  holds  the  client  ID,^  the  second  (integer)  field  holds  the  voting  sequence 
number  of  an  Accelerate  command,  etc. 

For  each  message  format,  a  macro  has  been  defined  that  produces  a  string 
in  that  message  format,  using  values  stored  in  a  variable  of  the  associated  data 

'Four  CPI  message  formats  are  associated  with  basic  data  types  that  are  not  explic¬ 
itly  defined  as  structures  in  cpi.h.  These  are  HSG.CPI-IIIT  (siring).  HSGJtCK  (string), 
HSGXPI J)DWILDJ)OIE  (integer)  and  HSOJJWITJILL  (string). 

*  A  unique  client  ID  is  eissigned  to  each  CPI  client  when  that  client  connects  to  a  simulation, 
as  described  below. 
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type  for  the  fields.  Another  macro  has  been  defined  for  parsing  such  a  mes¬ 
sage  into  a  variable  the  associated  data  type.  These  macros  are  provided  as 
a  convenience.  In  the  case  of  MSG_CPI_ACCEL,  the  creation  macro  is  called 
CreateMsgCPIAccel  and  is  defined  by  line  in  Figure  4.1.  The  message¬ 
parsing  macro  is  ParseMsgCPIAccel  defined  on  line  Q, 

In  general,  for  any  such  macro  associated  with  a  message  format; 

•  There  are  two  arguments,  a  character  string  buffer  holding  the  message 
and  a  pointer  to  a  variable  of  the  associated  data  structure  type  holding 
the  values. 

•  The  run-time  replacement  vedue  of  such  a  macro  is  the  length  of  the  re¬ 
sulting  message,  not  counting  a  null  byte  that  is  placed  at  the  end  of  that 
message  string.^ 

Thus,  the  macro  CreateMsgCPIAccel  behaves  like  a  function  with  the  following 
heading. 


int 

CreateMsgCPIAcceKbull ,  datap) 

char  buffD;  /*  resulting  message  is  placed  here  */ 
MsgCPIAccel  *datap;  /♦  points  to  data  values  */ 


4.3  Initiating  Communication 

Establishing  communication  between  a  client  and  a  Trainsot  railroad  simula¬ 
tion  requires  two  steps. 

1  Connection.  Create  a  network  connection  between  that  client  and  that 
simulation.  A  simulation  provides  well-known  ports  for  supported  commu¬ 
nication  protocol  families  (e.g.,  TCP/IP,  DECnet)  and  is  capable  of  socket 
or  stream  transmissions  in  each  case.  The  function  GetSimPort  defined  in 
the  source  file  lib/syslocal.c  returns  the  well-known  port,  given  a  base 
port  (provided  in  lib/syslocal  .h),  a  host  name  and  an  integer  simnum 
that  distinguishes  between  multiple  simulations  running  on  the  same  host. 
Use  standard  techniques  to  open  one  bidirectional  communication  line. 

2.  Registration.  Send  a  registration  message  to  that  simulation  to  declare 
a  client  type  (CPI  or  monitor)  and  receive  a  client  ID.  A  registration 
message  for  a  CPI  client  has  the  message  format  MSG_CPI_ISIT 

CPI  (one  space)  {string)  % 

^Sending  a  terminating  null  byte  to  a  simxilation  as  part  of  a  message  is  optional. 
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where  {string)  is  any  sequence  of  characters  that  are  not  the  percent  «ign 
%  and  is  conventionally  the  file  name  of  that  client’s  executable.  'I’he  sim¬ 
ulation  replies  with  an  acknowledgement  message  in  the  format  MSG_ACK, 
as  follows. 

ack  (one  space)  {integer)  t 

The  (integer)  field  in  that  message  represents  the  unique  client  ID  number 
to  be  used  in  all  commands  and  queries  from  that  client  to  the  simulation. 

The  macros  CreateMsgCPIInit  and  ParseMsgAck  may  be  used  if  desired. 

We  assume  that  each  client  creates  only  one  connection  with  a  simulation. 
For  the  remainder  of  this  chapter,  message  formats  will  be  cited  by  name 
only,  omitting  mention  of  syntax,  related  macros,  etc.  See  Appendix  C.l  for 
syntax  details. 


4.4  Initial- St  ate  Download 

After  initiating  communication  with  a  simulation,  a  CPI  client  can  receive  a 
report  of  the  current  global  state  of  the  railroad  being  simulated.  Such  a  report 
is  called  a  download. 

To  request  a  download,  a  control  program  must  send  a  message  to  a  simu¬ 
lation  using  the  message  format  MSG_CPI_DOWHLD_REQUEST.  The  acknowledge¬ 
ment  from  the  simulation  is  the  download  itself  The  download  consists  of 
messages  in  the  following  DOWHLD  formats. 

•  MSG_CPI_DO'WHLD_GENERAL  transmits  constants  that  describe  a  railroad  in 
general,  e.g.,  the  number  of  blocks. 

•  HSG_CPI_DOHRLD_TRAIK  describes  attributes  of  trains.  One  message  in 
this  format  is  sent  per  train. 

•  MSG_CPI_DOWHLD_BLOCK  describes  a  block.  MSG_CPI_DOWRLD_LIHK  gives 
block  attachments  for  a  block  as  described  in  Section  3.2.  One  message  in 
each  of  these  formats  is  sent  per  block. 

•  MSG_CPI_DQWIfLD_D01IE  marks  the  end  of  a  download. 

Only  one  download  request  is  honored  by  a  simulation  per  client  connection. 


4.5  Commands  and  Queries 

•  MSG_CPI_SET_SWITCH, MSG_CPI_ACCEL.  MSG_CPI_DECEL, 
MSG_CPI_SET_SPEED,  MSG_CPI_SET_DIR.  MSG_CPI_EHER_STQP  and 
MSG_CPI_STA_STQP  request  the  commands  described  in  Section  3.3.  No 
acknowledgement  message  is  sent  in  respon.se  to  such  a  command. 
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•  MSG_CPI_BLOCK_GCC  requests  a  block’s  occupancy  status.  A  simulation 
responds  with  a  message’’  "o"  if  that  block  is  occupied  or  "f"  (for  ‘free’") 
if  it  is  not  occupied. 

•  MSG_CPI_SWITCH_PQSIT  asks  for  the  current  setting  of  a  switch  block.  The 
response  is  "s"  for  straight,  "t"  for  turned,  or  *‘u"  for  undefined. 

•  MSG_CPI_TRAII_STATUS  inquires  about  a  train’s  status.  A  simulation  re¬ 
sponds  with  "r"  for  running  (operational  state)  or  "c"  for  crashed  (col¬ 
lided  or  derailed  states). 

•  MSG_CPI_TIlAII_MQTION  queries  whether  a  train  is  moving.  The  response 
is  "s"  for  stopped  or  "m"  for  moving.  A  train  is  moving  if  it  is  operational 
and  at  least  one  of  its  speed  and  acceleration  is  non-zero.  A  train  is 
stopped  if  it  is  not  moving. 


4.6  Quit  Message  From  the  Simulator 

Just  before  a  Trainset  simulation  exits  normally,  it  sends  a  message  in 
the  format  MSG.QUIT.ALL  to  all  of  its  clients.  Receipt  of  this  message  is  a 
certain  indicator  that  a  simulation  has  finished. 


*Note:  One-character  return  strings  such  as  "o"  are  sent  as  two-byte  messages  from  the 
simulator,  including  the  terminating  null  byte. 
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Appendix  A 

Constants  Used  by  Trainset 


Constant 

name 

Description 

Typical 

value 

Page 

references* 

ACC 

Standard  acceleration  rate  for  trains 

1.0  m/sec^ 

36.  40,  41.  42 

Aewer 

Emergency-stop  acceleration  rate  for  trains 

2.0  m/sec^ 

36,  37,  40.  43 

LE!S  cross 

Length  of  a  cross  block 

3.0  m 

33 

LEAjoia 

Length  of  a  join  block 

3.0  m 

32 

switch 

Length  of  a  switch  block 

3.0  m 

34 

Le 

Length  of  block  B 

35  to  300  m 

30 

K 

Length  of  train  r 

150  to  500  ni 

35 

Minimum  speed  limit  on  block  b 

0  m/sec 

30.  36.  40 

MX^ 

Mciximum  speed  limit  on  block  b 

60  m/sec 

30,  36.  40 

^blocks 

Number  of  blocks  in  a  layout 

0  to  50 

40 

^  trains 

Number  of  trains  in  a  layout 

1  to  3 

40 

Q  voting 

Voting  quorum 

2 

40.  45.  46 

^switch 

Time  for  a  switch  block  to  change  settings 

2  sec 

33.  40.  41 

C55, 

Station  stop  speed  for  a  station  block 

30  m/sec 

34,  37,  40.  43 

^  voting 

Voting  window 

5  sec 

40.  45,  46 

’  A  boldtace  number  indicates  the  primary  reference  for  a  symbol. 
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Appendix  B 


Code  Listings:  ACI 


B.l  aci.h,  Interface  Header  File 

/♦  aci.h  "  header  file  for  ACI. 

This  file  defines  types  and  constants  and  decleures  functions 
found  in  the  ACI  library  libaci.a  . 

Created  by  R.  Brown,  4/91  */ 

/*  all  units  axe  mks  unless  otherwise  indicated  */ 


/* 

*  constant  definitions 
♦/ 


#ifndef  MAX.TRAIHS 

#define  MAX.TRAIHS  10  /«  maximum  number  of  trains  in  a  layout 

# end if 

#ifndef  HAX.BLOCKS 

#define  MAX.BLOCKS  100  /*  maximum  number  of  blocks  in  a  layout  */ 

#endif 


/♦ 

*  type  definitions  for  storing  a  state  download 
*/ 
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/*  BlocXType  specifies  the  type  of  a  block  */ 

enujn  BlockType  {BT.REGULAR,  BT.STATIOH,  BT_SWITCH,  BT.JDIH,  BT.CROSS}; 


/*  BlockTypeData  represents  ’ata  that  is  specific  to  a  type  of  block  */ 
union  BlockTypeData  { 

struct  {  /*  BT_REGULAR  blocks  ♦/ 

int  tail,  head;  /*  terminators  */ 

>  rg: 

struct  {  /*  BT.STATIOH  blocks  */ 
int  tail,  head;  /*  terminators  •/ 
double  3ta_stop_speed;  /*  station  stop  speed  */ 

}  St; 

struct  {  /*  BT.SWITCH  blocks  */ 

int  tail,  straight,  turn;  /•  terminators  */ 

>  sh; 

struct  {  /*  BT.JOIH  blocks  */ 

int  tail,  headl,  head2;  /*  terminators  */ 

>  jn; 

struct  {  /*  BT.CROSS  (sub)blocks  ♦/ 

int  tail,  head;  /*  terminators  */ 

int  cross.id;  /*  block  ID  of  this  subblock’s  cross  block  */ 

>  cr; 

>; 


/♦  BlockData  represents  the  download  information  for  a  specific  block  */ 

typedef  struct  BlockData  < 

int  block.id;  /*  identifies  the  block  */ 
enum  BlockType  type; 
double  length; 

double  mai.speed,  min.speed;  /*  trains  derail  that  violate  these  limits  ♦/ 
union  BlockTypeData  t;  /♦  additional  data  that  depends  on  block  type  ♦/ 

}  BlockData; 
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/*  Location  specifies  a  position  sithin  a  block  */ 


struct  Location 

int  block;  /*  id  of  a  block  containing  the  location  */ 
double  offset;  /*  distance  from  tail  of  that  block  to  the  location  */ 
}  Location; 


/*  TrainData  represents  the  download  information  for  a  specific  train  */ 

typedef  struct  TrainData  < 

int  train.id;  /*  identifies  the  train  */ 
double  length; 

struct  Location  head,  tail;  /*  init  positions  of  train's  ends  */ 

}  TrainData; 


/*  LayoutData  represents  all  information  received  in  a  download  */ 

typedef  struct  LayoutData  { 

int  block. ct;  /*  number  of  blocks  */ 
int  train_ct;  /*  number  of  trains  */ 

double  acc,  emer.acc;  /*  standard  and  emergency  stop  acceleration  rates*/ 
double  switch.tirae;  /*  time  required  for  switch  block  to  change  posit  */ 
int  voting.quorum;  /*  number  of  agreeing  commands  required  for  an  action  */ 
double  voting.window;  /♦  time  limit  after  which  commands  expire  ♦/ 

BlockData  blocks [HAX.BLOCKS] ;  /*  block-specific  data  */ 

TrainData  trains [HAX.TRAINS] ;  /*  train-specific  data  */ 

)■  LayoutData; 


/♦ 

♦  ACI  function  declarations,  with  associated  type  definitions 

*/ 


/*  GetDownload,  for  connecting  to  a  simulated  railroad  and  receiving 
a  report  of  that  railroad’s  state.  •/ 

LayoutData  *GetDownload() ; 
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/*  ACI  commands  *! 


enum  NewPosit  {NP.STRAIGHT,  NP.TURRED}; 
void  SetSwitchO; 

void  AccelerateO; 

void  DecelerateO; 

void  SetSpeedO; 

void  SetDirectionO ; 

void  EmergancyStopO ; 

anum  StationStopMode  -{SS.DISABLED.  SS_EHABLED>; 
void  StationStopO ; 


/•  ACI  queries  */ 

enum  Occupancy  <0C_FREE,  OC.OCCUPIED,  OC.ERRDR  =  -1}; 
enum  Occupancy  GetBlockOccupancyO; 

enum  SwitchPosit  {SP.STRAIGHT,  SP.TURBED,  SP.UNDEFINED,  SP.ERROR  =  -1}; 
enum  SwitchPosit  GetSwitchPositionO ; 

enum  TrainStatus  {TS.CRASHED,  TS.RUNNIRG,  TS.ERRDR  =  -1}; 
enum  TrainStatus  GetTrainStatusO ; 

enum  TrainHotion  -(TM.STOPPED,  TM.MOVIHG,  TH.ERROR  =  -l}; 
enum  TrainHotion  GetTrainMotionO ; 


/*  changes  to  voting  service  sequence  number  ♦/ 
int  SetSeqNumber ( ) ; 
int  HewSeqSumberO ; 


/♦  timer  facility  */ 
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typedef  double  Seconds; 

enum  TimerReturn  {TMR.SUCCESS,  TMR.ERROR  =  -1}; 
enum  TimerReturn  InitTimerO; 

enum  TimerStatus  {TMS.DISABLED,  THS.OHCE,  TMS.IRDEFISITE,  TMS.ERROR  =  -1>; 
enum  TimerStatus  GetTimerO; 

void  AwaitTimer ( ) ; 

enum  TimerReturn  CancelTimerO ; 

enum  TimerRettirn  SleepO; 


B.2  acitest.c,  Example  Using  the  ACI  Inter¬ 
face 

/*  $RCSTile:  acitest.c, v  $  $Revision:  1.8  $  $Date:  92/07/17  10:58:43  $  */ 

/*  acitest.c  —  manual  demonstration  of  the  ACI  interface.  */ 

#include  <stdio,h> 

#include  "aci.h" 

#define  TIMEOUT  60.0  /*  seconds  to  contact  the  simulator  •/ 

tdefine  MAXLIHE  100  /*  maximum  input  length  */ 

^define  HORHAL  0  /*  exit  code  for  normal  exit  */ 

♦define  ERROR  1  /♦  exit  code  for  error  exit  */ 

♦define  USAGE  "Usage:  '/,s  [-d]  [simhost  Csimnum]]\n"  /*  diagnostic  msg  */ 
♦define  QUIT_C0MMAND  "q"  /*  user  entry  for  quit  command  */ 

enum  command.type  { 

/*  commands  */ 

SET.SWITCH  =  1,  ACCELERATE,  DECELERATE,  SET.SPEED, 

SET_DIRECTI0H,  EHERGENCY.STOP ,  STATIDH.STDP, 

/*  queries  */ 

GET_BL0CK_0CCUPAHCY,  GET. SWITCH _P0SITI ON,  GET.TRAIN.STATUS,  GET .TRAIN .MOTION, 
/*  other  ♦/ 

SET.SEq.NUMBER,  NEW.SEQ.NUMBER, 

QUIT,  HELP 

>: 


struct  command  { 
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enum  comraand.type  type;  /*  type  of  this  command  or  query  */ 

char  *code;  /*  entry  code  for  this  command  or  query  */ 

char  ♦name;  /♦  full  name  of  this  ACI  command  or  query  ♦/ 

char  *args ;  /♦  names  of  arguments  required  for  this  command  or  query  ♦/ 

>; 


/*  NULL- terminated  table  of  command  types,  codes  and  names  ♦/ 

struct  command  conimand_tablen  =  { 

/♦  commands  */ 

SET.SWITCH,  "sw",  "SetSHitch",  ‘■<block_id>  <neB_posit>" , 
ACCELERATE,  "ac",  "Accelerate",  ‘'<train_id>  <duration>", 

DECELERATE,  "dc",  "Decelerate",  "<train_id>  <duration>", 

SET_SPEED,  "sp",  "SetSpeed",  "<train_id>  <goal_speed>" , 
SET_DIRECTION,  "sd",  "SetDirection" ,  "<train_id>  <neH_dir>", 
EMERGENCY_STOP,  "es",  "EmergencyStop",  "<train_id>" , 
STATI0N_ST0P,  "st",  "StationStop" ,  "<train_id>  <neB_val>", 

/♦  queries  ♦/ 

GET.BLOCK.OCCUPARCY,  "o",  "GetBlockOccupancy" ,  "<block_id>" , 
GET_SWITCH_PQSITiaN,  "p",  "GetSsitchPosition" ,  "<block.id>", 
GET_TRAIN_STATUS,  "s",  "GetTrainStatus" ,  "<train_id>" , 
GET_TRAIN_MOTIOH,  "m",  "GetTrainMotion" ,  "<train_id>" , 

/♦  other  ♦/ 

SET.SEQ.NUMBER,  "sn",  "SetSeqNumber" ,  "<new_val>", 
NEW.SEQ.NUHBER,  "nn",  "NeuSeqNumber" ,  "", 

QUIT,  QUIT.COHMAND,  "Quit",  "", 

HELP,  "?",  "Help",  "  h  help", 

(enura  coramand.type)  0,  (char  *)  0,  (char  *)  0,  (char  *)  0 

>; 


/♦  Whitespace  takes  a  char  argument  c.  Evaluates  to  non-zero  if 
c  is  whitespace,  zero  otherwise  ♦/ 

#define  Whitespace(c)  (c  ==  *  '  | |  c  ==  ’\t’  I  I  c  ==  ’\n’) 


/***Dc*«itciti*4i*it'****4>«*^^«4>**«**4>4’*^**e**«*4>«****#*4>«4>**4^«****4>*«***/ 

/*  CommandLookup  determines  the  command  corresponding  to  a  code 
entered  to  identify  a  command. 

Any  whitespace  characters  at  the  beginning  of  entry  are  ignored. 
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Returns  the  index  in  the  table  of  the  indicated  command,  or 

-1  il  the  code  was  empty  or  the  given  entry  code  was  not  found.  */ 


int 

C  ommandLookup ( ent  r y ) 

char  ♦entry;  /♦  entry  code  to  be  interpreted  as  a  command  •/ 

{ 

struct  command  *p;  /*  pointer  into  command  table  */ 

whilo  (♦entry  Whitespace (♦entry) ) 

entry++ ; 
if  ((♦entry) 
return  (-1); 

/*  entry  is  non-empty  string  beginning  with  a  non-nhitespace  char  */ 

if  (♦entry  ==  ’h’) 
entry  = 

/♦  if  request  is  for  Help  then  entry  has  value  "?"  ♦/ 

for  (p  =  command. table;  p->type;  p++)  { 
if  (! strcmp (entry ,  p->code))  { 
return  (p  -  command.table) ; 

> 

} 

/♦  entry  does  not  match  a  code  in  the  table  ♦/ 

print!  ("  no  match  foundW); 
return  (-1); 


/#**  *  4c  ^■♦♦♦♦♦♦♦^♦♦♦^♦♦♦♦♦♦♦♦♦♦^♦♦*««4<^^^^^  ♦♦♦♦♦♦♦♦♦«♦♦♦♦♦♦♦  ♦♦♦♦♦/ 

/♦  PrintDownload  displays  every  field  received  in  a  download  ♦/ 
void 

PrintDownload (dp,  simhost,  simnum) 

LayoutData  ♦dp;  /*  data  received  from  download  ♦/ 

char  ♦simhost;  /♦  name  of  the  host  system  running  the  simulator  */ 

int  simnum;  /♦  identifier  for  a  running  simulation  on  that  host  ♦/ 

■C 

int  i;  /♦  loop  control  ♦/ 

TrainData  *tp;  /♦  utility  pointer  to  data  for  a  specific  train  ♦/ 
BlockData  *bp;  /♦  utility  pointer  to  data  for  a  specific  block  ♦/ 


62 


printf ("Contents  of  download  from  simhost  '/,s,  simnum  */,d:\n", 
simhost,  simnum); 

printf ("NnGaneral  parameters ;\n") ; 
printfC"  There  are  ‘/.d  blocks  and  '/A  trains \n", 
dp->block_ct,  dp->train_ct) ; 

printfC"  Train  acceleration  rates  (m/sec) ;  standeurd  ‘/.f,  emergency  stop  ‘/.f  \n" , 
dp->acc ,  dp->emer_acc) ; 

printfC"  Switches  take  ‘/,f  seconds  to  change  positionVn", 
dp->switch_time) ; 

printfC"  The  voting  quorum  is  ‘/.d  and  the  voting  window  is  */,f  secondsXn", 
dp- > voting .quorum,  dp->voting_window) ; 

printf ("\nBlocks ; \n" ) ; 
for  Ci=0:  i  <  dp->block_ct;  i++)  { 
bp  =  ftdp->blocks [i] ; 

printfC"  Block  */,d  has  type  ",  bp->block_id) ; 
switch  (bp->type)  { 
case  BT.REGULAR: 
printf ("REGULAR"); 
break; 

case  BT.STATIOH: 
printf ("STATION"); 
break; 

case  BT.SWITCH: 
printf ("SWITCH"); 
break; 

case  BT.JOIN: 
printf ("JOIN"); 
break; 

case  BT.CROSS: 
printf ("CROSS"); 
break; 

} 

printfC"  and  length  */,f  meters\n",  bp->length); 

printfC"  Its  speed  limits  are  '/,f  (minimum)  and  '/,t  (maximum) \n", 
bp->min_ spaed,  bp->max_8peed) ; 
printfC"  Its  terminators  are  connected  to  blocks  "); 
switch  (bp->type)  •( 
case  BT.REGULAR: 

printf  ("'/,d  (head)  and  '/,d  (tail)\n'*. 
bp->t.rg.h8ad,  bp->t.rg.tail); 
break; 
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case  BT.STATION: 

printf("'/.d  (head)  and  ‘/.d  (tail)\n", 
bp->t.st.head,  bp->t.st.tail); 

print! ("  Its  station  stop  speed  is  '/,f  m/sec\n", 
bp->t . St . sta_stop_speed) ; 
break; 

case  BT.SWITCH; 

printf("*/,d  (straight  head),  '/.d  (turn  head)  and  '/,d  (tail)\n", 
bp->t.sH. straight,  bp->t.sB.turn,  bp->t .sw.tail) ; 
break; 

case  BT_30I!I: 

print!("y.d  (headl),  ’/.d  (head2)  and  ‘/,d  (tail)\n", 
bp->t. jn.headl,  bp->t. jn.head2,  bp->t. jn.tail) ; 
break; 

case  BT.CROSS: 

printf("’/,d  (head)  and  Xd  (tail)\n", 
bp->t.cr.head,  bp->t.cr.tail) ; 

print! ("  This  is  a  subblock  o!  the  cross  block  with  ID  */,d\n" , 
bp->t . cr . cross.id) ; 
break; 

} 

> 

print! ( " \nTr ains : \n" ) ; 

!or  (i®0;  i  <  dp->train_ct;  i++)  { 
tp  =  (tdp->trains  Ci]  ; 

print!  ("  Train  ‘/.d  has  length  '/.!  raetersNn", 
tp->tTain_id,  tp->length); 

print! ("  Its  head  end  is  in  block  ‘/id,  '/,!  meters  !rom  tail  terminator \n" 
tp->head .block ,  tp->bead . o!!set) ; 

print!("  Its  tail  end  is  in  block  */,d,  */,!  meters  !rom  tail  terminator \a" 
tp->tail . block ,  tp->tail . o!!set ) ; 

> 

print!("\nEnd  o!  con!iguration  download  reportXnNn") ; 
return; 


/*  GetValue  attempts  to  locate  a  value  in  the  string  bu!f. 

If  bull  contains  only  whitespace,  prompt  is  printed  and  standard  input 
is  read  until  some  non-whitespace  characters  are  entered. 
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If  a  value  matching  the  printf  format  fmt  is  found  in  buff  or  stdin, 
then  its  value  is  placed  in  *valp  and  a  pointer  is  returned  that  points 
to  the  first  whitespace  character  after  the  value. 

If  the  next  non-whitespace  characters  do  not  scan  according  to  fmt, 
an  error  message  requesting  user  to  try  again  is  printed  and 
NULL  is  returned.  */ 

char  ♦ 

GetValueCbuff ,  fmt.  valp,  prompt) 

char  *buff;  /♦  buffer  that  may  contain  a  value  */ 

char  ♦fmt;  /♦  printf-style  format  for  reading  the  value  */ 

char  ♦valp;  /♦  to  receive  value  if  one  is  found  ♦/ 

char  ♦prompt;  /♦  prompt,  used  to  obtain  standard  input  ♦/ 

< 

char  ♦p;  /♦  utility  pointer  ♦/ 

/♦  invar:  buff  is  unexamined  ♦/ 
do  { 

for  (p  =  buff;  ♦p  ftft  Whitespace(^p) ;  p++) 

I 

/*  *p  is  null-byte  or  first  non-whitespace  ♦/ 
if  (l^p)  < 

printf ("  y.s:  ",  prompt); 
getsCbuff ) ; 
p  =  buff; 

> 

/♦  ♦p  is  first  non-whitespace  char,  or  p  points  to  beginning  of 
an  unexamined  (yet  possibly  empty)  buff  ♦/ 

>  while  ('♦p  II  Whitespace(^p)); 

/♦  ♦p  is  non-whitespace  */ 

if  (sscanfCp,  fmt,  valp)  !=  1)  { 
printf ("Error  reading  value  —  try  againXn"); 
return  (HULL); 

} 

/♦  value  was  successfully  read  into  ♦valp  ♦/ 

while  (♦p  ftJE  !Shitespace(^p)) 

P++: 

return  (p) ; 

} 
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/♦  Getint  and  GetFloat  are  macros  for  getting  values  of  certain  types 
from  buffD  or  standard  input,  via  GetValue  above  */ 


#define  Getlnt(buff,  valp,  prompt)  GetValue  (buff ,  '"/.d",  valp,  prompt) 
#define  GetFloat  (buff ,  valp,  prompt)  GetValue  (buff ,  "‘/.If",  valp,  prompt) 


main(argc,  argv) 

int  argc;  /*  number  of  command  line  arguments  remaining  ♦/ 
char  ■•■argvD;  /*  list  of  command  line  arguments  remaining  */ 

t 

\ 

char  *progname;  /♦  name  of  this  program  */ 

char  3imhost[MAXLIHE+l] ;  /*  name  of  host  system  running  simulator  */ 

int  simnum  =0;  /*  number  of  this  simulator  */ 

int  print_doBnload  =0;  /•  boolean;  set  non-zero  to  print  dounload  */ 

char  buf f [MAXLIIE+l] ;  /*  buffer  for  interactive  input  */ 

LayoutData  *datap;  /♦  data  received  from  dounload  */ 

int  index;  /*  index  of  a  command  table  entry  «/ 

char  *p,  eetablep;  /*  utility  pointers  •/ 

struct  command  *commandp;  f*  pointer  into  command  table  */ 

char  prompt [MAXLIHE] ;  /*  holds  any  prompts  for  user  input  */ 

p  =  progname  =  ♦argv++;  argc — ; 

I*  invar;  there  are  no  slashes  in  the  string  progname  before  p  */ 
while  (*p) 

if  (*p++  ==  >/’) 
progname  =  p; 

/*  progname  is  null-terminated  program  name  after  stripping  directories  */ 

if  (argc  >  0  4ft  ♦♦argv  ==  ’-’)■( 

/♦  a  flag  was  encountered  ♦/ 
if  ( !strcmp(^argv,  "-d"))  { 
print _download++ ; 
argc— ;  argv++ ; 

>  else  < 

fprintf (stderr,  USAGE,  progname;; 
exit  (ERROR) ; 

} 

} 

/♦  all  flags  have  been  processed  ♦/ 
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if  (argc  >  0)  { 

/*  a  next  argument  exists,  presumed  to  be  simhost  */ 
if  (strlenC't'argv)  >  MAXLINE)  { 

fprintl (stdorr,  "simulator  host  name  too  long,  max  =  '/.d\n”,  MAXLIHE); 
exit  (ERROR) ; 

} 

/*  first  arg  uill  lit  in  simhost  •/ 

strcpyCsimhost,  ♦argv++): 
argc--; 

}  else  { 

/*  no  more  command-line  arguments  remain  */ 

print! ("Enter  name  o!  host  running  simulator  [LOCAL  HOST];  "); 
i!  (! gets (simhost))  { 

!printf (stderr,  "error  getting  host  name\n"); 
exit  (ERROR) ; 

} 

print! ("Enter  simulator  number  on  that  host  [03:  "); 
i!  (! gets (bull))  { 

!print! (stderr,  "error  getting  simulator  number\n"); 
exit  (ERROR): 

} 

simnum  =  (*bu!!)  ?  atoi(bu!!)  :  0; 

> 

/♦  simhost  contains  (possibly  empty)  null-terminated  string  AND 

i!  no  argument  remains  then  simnum  holds  speci!ied  or  de!ault  value  */ 

i!  (argc  >  0)  { 

I*  another  argument  second  parameter  exists,  presumed  to  be  simniun  */ 

sscan!(*argv++,  '"/•d",  ftsimnum); 

argc--; 

} 

I*  simnum  holds  speci!ied  or  de!ault  value  */ 

print! ("Connecting  to  simulator  using  '/,.l!  second  timeout.  .  An" ,  TIMEOUT); 
i!  ( ! (datap  =  GetDo«nload(simhost,  simnum,  progname,  TIMEOUT)))  -[ 

!print! (stderr,  "GetDownload  !ailod\n"); 
exit  (ERROR) ; 

} 

/•  download  was  success!ully  received  */ 
i!  (print.download) 
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PrintDosnloadCdatap,  simhost,  simnum); 

printi ("Enter  ?  for  a  list  of  commands\n** ) ; 

for  ( ; ; )  { 
do  •( 

printf ('"/,s>  ”,  progname);  /♦  prompt  */ 

buff[0]  =  >\0’; 
if  ( !get3(buff)) 

/♦  end  of  input  encountered  */ 
sprintf  (buff ,  QUIT.COMMAlfD ) : 

for  (p=buff;  *p  ftft  Whitospace(*p) ;  p++) 

> 

/»  p  points  to  first  non-wbitespace  char  of  buff,  or  null  byte  */ 

}  while  (l♦p): 

/•  buff  n  contains  a  new  non-empty  null-terminated  command  */ 
while  (*p  ! Whitespace (»p)) 

P++; 

/♦  ep  is  null-byte  or  first  whitespace  after  command  code  */ 
if  (*p) 

*p++  =  '\0>: 

/*  buff  is  null-terminated  string  holding  a  non-empty  command  code 

consisting  of  non-whitespace  chars,  and  holding  QUIT.COHMASD  on  EOF, 
AID  string  p  is  any  remainder  of  the  (null-terminated)  input  line  */ 

if  ((index  =  ComBandLookup(buff ) )  ==  -1)  { 

printf  ("Unrecognized  command  code  “/.s’  (enter  '?’  for  help)\n", 
buff); 
continue; 

> 

a  recognized  command  code  was  entered  */ 

/*  gather  arguments  for  the  appropriate  ACI  routine  and  call  it  */ 

switch  (command_table [index] .type)  { 
case  SET.SWITCH: 

int  block.id;  /*  identifier  of  the  switch  block  */ 
enxun  HewPosit  new_posit;  /♦  desired  position  */ 

p  =  Getlnt(p,  ftblock_id,  "SetSwitch.  ID  of  switch  block"); 
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il  (!p)  continue; 


sprint! (prompt ,  "Hes  position  (‘/.d  =  straight,  '/,d  =  turned)", 
NP.STRAIGHT,  KP.TURNED); 
p  =  GetIntCp,  <tneH_posit,  prompt); 
if  (!p)  continue; 

/♦  all  arguments  successfully  obtained  ♦/ 

SetSwitch(block_id,  new.posit); 
break; 

> 

case  ACCELERATE: 
case  DECELERATE; 

{ 

int  train.id;  /*  identifier  of  the  train  */ 

double  duration;  I*  number  of  seconds  to  accelerate  */ 

sprint!  (prompt ,  "*/,s.  ID  of  train",  command_t  able  [index]  .name) 
p  =  Getlnt(p,  fttrain.id,  prompt); 
if  (!p)  continue; 

sprintf  (prompt,  "Seconds  to  ‘/,s",  command_table [index]  .name) ; 
p  =  GotFloat(p,  ^duration,  prompt); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

if  (command.table [index] .type  ==  ACCELERATE) 
Accolerate(train_id,  duration); 
else 

Doceleratc(train_id,  duration); 
break; 

} 

case  SET.SPEED : 

int  train.id;  /*  identifier  of  the  train  */ 

double  goal_speed;  /♦  speed  to  accelerate  or  decelerate  to  ♦/ 

p  =  Getlnt(p,  *train_id,  "SetSpeed.  ID  of  train"); 
if  (Ip)  continue; 

p  =  GetFloat(p,  ftgoal_speed,  "Hew  goal  speed"); 
if  (Ip)  continue; 
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/♦  all  arguments  successfully  obt^  .led  */ 

SetSpeed(train_id,  goal.speed); 
break; 

} 

case  SET.DIRECTIOI : 

int  train.id;  /*  identifier  of  tbe  crain  •/ 
int  neB_dir;  /*  indicator  of  nes  direction  ♦/ 

p  =  GetIntCp,  4train_id,  "SetDirection.  ID  of  train"): 
if  (!p)  continue; 

p  =  GetIntCp,  toes.dir, 

"Hes  direction  (+1  for  front=head,  -1  for  front=tail,  0  to  toggle)"); 
if  (ip)  continue; 

/*  all  arguments  successfully  obtained  */ 

SetDirection(train_id,  nes.dir); 
break; 

} 

case  EMERGEHCY.STOP : 

{ 

int  train_id;  /*  identifier  of  the  train  */ 

p  =  GetIntCp,  fttrain.id,  "EmergencyStop.  ID  of  train  to  stop"); 
if  (ip)  continue; 

/*  all  arguments  successfully  obtained  */ 

EmorgencyStopCtrain.id) ; 
break; 

} 

case  STATIOH.STOP: 

i 

int  train_id;  /*  identifier  of  the  train  ♦/ 
enum  StationStopMode  nen.val; 

p  =  GetIntCp,  4train_id,  "StationStop.  ID  of  train"); 
if  (ip)  continue; 

sprintf (prompt ,  "Hew  mode  ('/,d  =  disabled,  '4d  =  enabled)". 
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SS.DISABLED .  SS_ENABLED) ; 
p  =  Getliit(p,  ftnen.val,  prompt); 

/♦  all  arguments  successfully  obtained  ♦/ 

StationStop(train_id,  neu.val); 
break; 

} 

case  GET_BLOCK_OCCUPABrCY : 

int  block_id;  /♦  identifier  of  the  block  *! 

enum  Occupancy  occ;  /*  return  value  from  the  query  */ 

p  =  GetIntCp,  &block_id,  "GetBlockOccupancy .  ID  of  block"); 
if  (!p)  continue; 

/♦  all  arguments  successfully  obtained  */ 
occ  =  GetBlockOccupancy(block_id) ; 
if  (occ  ==  OC.FREE) 

printf  ("Block  ’/,d  is  FREE  (unoccupied) .  \n" ,  block.id); 
else  if  (occ  ==  OC.OCCUPIED) 
printf  ("Block ‘/.d  is  OCCUPIED .  \n" ,  block.id); 
else  /*  occ  ==  OC.ERROR  */ 

printf  ("Unable  to  obtain  occupancy  for  block  '/,d\n",  block_id); 
break; 

> 

case  GET.SWITCH.POSITION : 

{ 

int  block.id;  /*  identifier  of  the  switch  block  */ 
enum  SwitchPosit  posit;  /*  return  value  from  the  query  */ 

p  =  Getlnt(p,  *block_id,  "GetSwitchPosition.  ID  of  switch  block"); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 

posit  =  GetSwitchPosition(block_id) ; 

if  (posit  ==  SP.STRAIGHT) 

printf  ("Switch  block  '/,d  is  STRAIGHT\n",  block^id); 
else  if  (posit  ==  SP_TURHED) 

printf  ("Switch  block  ’/.d  is  TURHED\n",  block.id); 
else  if  (posit  ==  SP_UHDEFIHED) 
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print! ("Switch  block  */,d  has  UNDEFINED  position\n",  block_id); 
else  /*  posit  ==  SP_ERRQR  */ 

print!  ("Unable  to  obtain  position  o!  switch  block  '/,d\n“,  block_id) ; 
break; 

} 

case  GET_TRAIN_STATUS: 

int  train_id;  /*  identi!ier  o!  the  train  ♦/ 

enum  TrainStatus  status;  /•  return  value  iron  the  query  */ 

p  =  Getlnt(p,  fttrain_id,  "GetTrainStatus .  ID  o!  train"); 
if  (!p)  continue; 

/*  all  arguments  success!ully  obtained  •/ 

status  =  GetTrainStatus (train_id ) ; 

if  (status  ==  TS.CRASHED) 
print! ("Train  '/,d  has  CRASHEDXn",  train.id) ; 
else  if  (status  ==  TS.RUNNING) 
print!  ("Train  ‘/.d  is  RUNNINGXn",  train_id); 
else  /*  Status  ==  TS_ERROR  */ 

print!  ("Unable  to  tain  status  o!  tra_n  '/,d\n",  train_id); 
break; 

> 

case  GET .TRAIN .MOTION: 

{ 

int  train.id;  /*  identifier  of  the  train  ♦/ 

enum  TrainMotion  motion;  /*  return  value  from  the  query  */ 

p  =  Getlnt(p,  fttrain_id,  "GetTrainMotion,  ID  of  train"); 
if  (!p)  continue; 

/•  all  arguments  successfully  obtained  */ 

motion  =  GotTrainMotion(train.id); 

if  (motion  ==  TM.STOPPED) 

printf ("Train  '/,d  is  STOPPEDNn",  train.id); 
else  if  (motion  ==  TH.MOVING) 

printf ( "Train  */.d  is  M0VING\n",  train.id); 
else  /*  motion  ==  TH.ERROR  */ 

printf  ("Unable  to  obtain  motion  information  for  train  */id\n" , 


72 


train. id) ; 
break; 

> 

case  SET.SEq.HUMBER: 

i 

int  new.val;  /*  new  value  for  sequence  number  */ 
int  seq.num;  /*  return  value  from  SetSeqNumber  ♦/ 

p  =  Getlnt(p,  ftnew.val,  "SetSeqNumber.  New  sequence  number  value”); 
if  (!p)  continue; 

/*  all  arguments  successfully  obtained  */ 
seq.num  =  SetSeqNumber (new. val) ; 

printf  ("Current  sequence  number  value:  */.d\n",  seq.num) ; 
brecik; 

} 

case  NEW.SEQ.NUMBER: 

< 

int  seq.num;  /*  return  value  from  NeBSeqHumber  */ 
seq.num  =  NewSeqNumberO ; 

printf  ("Current  sequence  number  value:  */,d\n",  seq.num); 
break; 

> 

case  QUIT: 

char  conf irmCMAXLINE+1] ;  /*  confirmation  string  ♦/ 

printf ("Quit .  Are  you  sure  you  want  to  quit?\n  (y/n,  default  y)  "); 
gets (confirm) ; 

/♦  confirmation  response  has  been  received  */ 

if  (♦confirm  ==  ’\0’  II  ♦confirm  ==  ’y’  II  ♦confirm  ==  ’Y’) 
exit  (NORMAL): 
break; 

} 

case  HELP: 
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struct  command  *cp;  /*  pointer  into  command_table  */ 


printf  ("*/,-34s*/!s\n - \n*' , 

"entry",  "ACl  command"); 
for  (cp  =  command_table;  cp->code;  cp++)  { 

print!'  ‘  ’ '•V,-30s*/.s\n" ,  cp->code,  cp->args.  cp->name); 

> 

break; 

} 

default : 

printf (“Unre  rnized  command  \"*/,s\"\nEnter  ?  for  helpNn",  buff); 

break; 


Appendix  C 

Code  Listings:  LLI 


C,1  cpi.h,  Interface  Header  File 

/♦  $RCSfile;  cpi.h, v  $  SRevision:  1.66  $  $Date;  92/11/24  14:41:00  $  ♦/ 
/*  cpi.h  —  cpi  message  formats.  */ 

/*  This  file  automatically  generated  by  m4  from  cpi.hm  ♦/ 


/♦  Messages  for  initial  and  final  communication  with  simulator  ♦/ 

/♦  first  message  for  simulator,  identifying  self  as  a  CPI  client  ♦/ 
#define  MSG.CPI.IKIT  "CPI 
#define  HSG.CPI_INIT_ARGC  1 

#define  CreateMsgCPIInit 'buff ,  str)  sprintf (buff ,  MSG_CPI_INIT,  (str)) 
#define  ParseHsgCPIInit{buff ,  str)  sscanf(buff,  MSG_CPI_INIT,  (str)) 


/*  standard  acknowledgement  message  format;  client  ID  is  return  value  */ 
♦define  MSG.ACK  "ack  ‘/.s'/,'/." 

♦define  MSG_ACK_ARGC  1 

♦define  CreateHsgAck(buff ,  str)  sprintf (buff ,  MSG_ACK,  (str)) 

♦define  ParseMsgAck(buff ,  str)  sscanf(buff,  MSG.ACK,  (str)) 


/♦  simulator  sends  the  following  message  to  all  clients  upon  normal  exit  */ 
♦define  MSG_QUIT_ALL  "QUIT.ALL  'UVU," 

♦define  KSG_qUIT_ALL_ARGC  1 

♦define  CreateMsgQuitAlKbuff ,  str)  sprintf (buff ,  MSG_QUIT_ALL,  (str)) 
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#deline  ParseHsgQuitAlKbuff ,  str)  sscaiif(buff ,  HSG_QUIT_ALL,  (str)) 


/««*«*iti4i*«#««4<***«i^*4>***«*>l>*«****»««***4<  *«*«'*>»***•**********«***>•<*  **********/ 

/*  Messages  lor  configuration  download.  RAB  and  JG  4/90  rev  5/91  */ 

#define  HSG_CPI_DOWNLD_REQUEST  "CPI  Downld  request  from  '/.s'/.*/." 

#define  HSG_CPI_DOWKLD_REqUEST_ARGC  1 
#define  CreateMsgCPIDosnldRequestCbuff ,  str)  \ 
sprintfCbuff ,  HSG_CPI_DOWNLD_REQUEST.  (str)) 

#define  ParseMsgCPIDownldRequestCbuff ,  str)  \ 
sscanf(buff,  MSG.CPI.DOWNLD.REQUEST,  (str)) 


#define  MSG_.CPI_DOWNLD_GEHERAL  "C  ’/.d.y.d.’/.lf ,'/.lf .'/.If .'/.d.’/.lf#" 
typedef  struct  { 

int  block_ct,  train.ct;  /*  number  of  blocks  and  trains  in  layout  ♦/ 
double  acc,  emer_acc;  /*  standard  and  emergency  stop  acceleration  rates  »/ 
double  switch.time;  /*  time  required  for  switch  block  to  change  posit  */ 
int  voting.quorum;  /*  number  of  agreeing  commands  required  for  an  action  */ 
double  voting_window;  /*  time  limit  after  which  commands  expire  */ 

>  MsgCPIDownldGeneral ; 

#define  HSG_CPI_DOWNLD_GENERAL_AEGC  7 

#def ine  MsgCPIDownldGeneralArgs(buff ,  datap)  (buff,  HSG_CPI_DOWRLD_GENERAL,  \ 
datap->block_ct  ,  datap->train_ct  ,  datap->acc  ,  datap->emer_acc  .  \ 
datap->switch_time  ,  datap->voting_quorum  ,  datap->votiag_window  ) 

#define  CreateMsgCPIDownldGeneral(buff ,  datap)  \ 
sprintf  HsgCPIDownldGeneralArgs(buff ,  (datap)) 

#define  ParseMsgCPIDownldGeneralCbuff ,  datap)  \ 
sscanf  HsgCPIDownldGeneralArgs(buff ,  ft(datap)) 


#def ine  MSG_CPI_DOWHLD_TRAIH  "T'/.d.’/.ll ,'/.d,'/.lf  .’/.d.'/.H#" 
typedef  struct  { 

int  train_id;  /♦  numerical  name  of  this  train  ♦/ 
double  length;  /*  length  of  train  */ 

int  head_block;  /*  block_id  for  block  holding  train  head  ♦/ 
double  head_offset;  /♦  offset  within  head_block  of  train  head  */ 
int  tail_block;  /*  block.id  for  block  holding  train  tail  •/ 
double  tail_offset;  /♦  offset  within  tail_block  of  train  tail  */ 
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>  MsgCPIDownldTrain; 


#deline  MSG_CPI_DQVI1ILD_TRAIS_ARGC  6 

^define  MsgCPIDosnldTrainArgsCbulf ,  datap)  (bulf,  MSG_CPI_DQWNLD_TRAIH ,  \ 
datap->train_id  ,  datap->length  ,  datap- >head_block  ,  datap->head_off set  ,  \ 
datap->tail_block  i  datap->tail_oilset  ) 

#define  CreateMsgCPIDosnldTrainCbuff ,  datap)  \ 
sprintf  MsgCPIDoHuldTrainArgsCbufl ,  (datap)) 

#deline  ParseHsgCPIDownldTrain(buff ,  datap)  \ 
sscanf  MsgCPIDownldTrainArgs(bulf ,  ft(datap)) 


#deline  MSG_CPI_DOWNLD_BLOCK  ••B‘/.d,*/,lf .'/.d.y.lf  .'/.If  .’/.d#" 

typedef  struct  i 

int  block_id:  /*  numerical  name  of  this  block  */ 

double  length;  /*  length  of  the  block  in  meters  */ 

int  type;  /*  code  for  type  classification  of  this  block  •/ 

double  max_speed,  min_speed;  /*  speed  above/belou  which  derailment  occurs*/ 

double  sta_stop_speed;  /*  highest  station  stop  speed - sta  blocks  only  »/ 

int  cross_id;  /*  id  for  the  cross  block— for  cross  subblocks  only  */ 

)•  MsgCPIDownldBlock; 

#define  MSG.CPI_DOWNLD_BLOCK.ARGC  7 

#define  MsgCPIDownldBlockArgs(buff ,  datap)  (buff,  MSG.CPI.DOWNLD.BLDCK,  \ 
datap->block_id  ,  datap->length  ,  datap->type  ,  datap->max_speed  ,  \ 
datap- >min_speed  ,  datap->sta_stop_speed  ,  datap->cross_id  ) 

#define  CreateMsgCPIDownldBlock(buff ,  datap)  \ 
sprintf  HsgCPIDownldBlockArgs(buff ,  (datap)) 

#define  ParseMsgCPIDownldBlock(buff ,  datap)  \ 
sscanf  HsgCPIDownldBlockArgs(buff ,  4(datap)) 


#define  MSG.CPI.DOWNLD.LINK  "L'/.d.'/.d.'/.d.’/.d.'/.d#" 
typedef  struct  ■( 

int  block.id;  /*  numerical  name  of  this  block  */ 

int  type;  /*  code  for  type  classification  of  this  block  */ 

int  tail,  headl,  head2;  /*  block.ids  for  adjoining  blocks  */ 

}  MsgCPIDonnldLink; 

#define  MSG.CPI.DOWNLD.LINK.ARGC  6 

#define  MsgCPIDownldLinkArgs(buff ,  datap)  (buff,  MSG_CPI_DOWNLD_LINK,  \ 
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datap->bloclc_id  ,  datap->type  ,  datap->tail  ,  datap->headl  ,  datap->head2  ) 


#define  CreateMsgCPIDosnldLinltCbuff ,  datap)  \ 
sprintf  MsgCPIDownldLinkArgsCbufl ,  (datap)) 
#deline  PaxseHsgCPIDopnldLink(buff ,  datap)  \ 
sscanf  HsgCPIDowaldLinkArgs(bufl ,  &(datap)) 


/*  Tbe  end  ot  an  cpi  conlig  download  may  be  recognized  by  searching  for 

CPI_DOWHLD_TERM  beginning  CPI,DOWBLD_TEaM_OFFSET  from  final  char  received*/ 

#define  CPI_DOWNLD_TERM  ’D’ 

•define  CPI.DOMNLD.TERM.OFFSET  -4 

•define  HSG_CPI_DQWNLD_DONE  "D  V.d*" 

•define  MSG_CPI_DOWHLD_DO»E_ARGC  1 
•define  CreateMsgCPIDownldDoneCbuff ,  val)  \ 
sprintfCbuff ,  MSG_CPI_D0WNLD_D01!E,  (val)) 

•define  ParseHsgCPIDoHnldDone(buff ,  val)  \ 
sscanf(buff,  MSG_CPI_DOWNLD_DOSE,  4(val)) 


/^l**^^*^Hlltt!tl^ll^^<^:tl^,*^^^lt*itl)l^^^l,^*m*********^‘*************^i******’¥^^*****^‘*m**********/ 

/*  Commands  ♦/ 

•define  MSG_CPI_SET_SWITCH  "Xh'/,d,'/.d;'/.d:'/.d#" 
typedef  struct  •( 

int  client_id;  /*  unique  identifier  lor  this  client  */ 
int  seq_num;  /*  label  for  this  command  */ 
int  block_id;  /♦  simulator  block  number  */ 

int  new.posit;  /*  new  switch  position — 0  lor  straight  and  1  for  turned  */ 

}  MsgCPISetSwitch; 

•define  MSG_CPI_SET_SWITCH_ARGC  4 

•define  MsgCPISetSwitchArgs(bulf ,  datap)  (bull,  MSG_CPI_SET_SWITCH,  \ 
datap->client_id  ,  datap->seq_num  ,  datap->block_id  ,  datap->new_posit  ) 

•define  CreateMsgCPISetSwitch(buff ,  datap)  \ 
sprint!  MsgCPISetSwitchArgs(buff ,  (datap)) 

•define  ParseHsgCPISetSwitch(buff ,  datap)  \ 
sscanf  MsgCPISetSwitchArgs(buff ,  A (datap)) 
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#deline  MSG_CPI_ACCEL  "Xa’/.d,*/.d:*/.d:’/.lf#" 
typedef  struct  ■{ 

int  client_id;  /♦  unique  identifier  for  this  client  ♦/ 
int  seq_nuiB;  /♦  label  for  this  commamd  */ 
int  train_id;  /*  simulator  train  number  ♦/ 
double  duration;  /•  time  to  accelerate  in  seconds  */ 

}  MsgCPIAccel; 

#define  MSG_CPI_ACCEL_ARGC  4 

#define  MsgCPIAccelArgs(buff ,  datap)  (buff,  MSG_CPI_ACCEL,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->duration  ) 

#define  CreateMsgCPIAcceKbuff ,  datap)  sprintf  MsgCPIAccelArgs(buff ,  (datap)) 
#define  ParseMsgCPIAcceKbuff ,  datap)  sscanf  MsgCPIAccelArgs(buff ,  ft(datap)) 


#define  MSG_CPI_DECEL  '’Xd'/.d.y.d;'/.d;*/.lf#" 
typedef  struct  < 

int  client.id;  /*  unique  identifier  for  this  client  •/ 
int  seq.num;  /♦  label  for  this  command  */ 
int  train_id;  /*  simulator  train  number  */ 
double  duration;  /*  time  to  decelerate  in  seconds  ♦/ 

}  HsgCPIDecel; 

#define  HSG_CPI_DECEL_ARGC  4 

#define  MsgCPIDecclArgs(buff ,  datap)  (buff,  «SG_CPI_DECEL,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->duration  ) 

#define  CreateMsgCPIDeceKbuff ,  datap)  sprintf  MsgCPIDecelArgs(buff ,  (datap)) 
#define  ParseMsgCPIDecel(buff ,  datap)  sscanf  HsgCPlDecelArgsCbuff .  ft(datap)) 


#define  MSG_CPI_SET_SPEED  "Xvy.d,*/.d:y.d:y.lf#’' 
typedef  struct  { 

int  client_id;  /*  unique  identifier  for  this  client  ♦/ 
int  seq_num;  /♦  label  for  this  command  */ 
int  train_id;  /*  simulator  train  number  */ 
double  goal.speed;  /♦  new  desired  velocity  for  the  train  */ 

}  MsgCPISetSpeed; 

#define  MSG_CPI_SET_SPEED_ARGC  4 

tdefine  MsgCPISetSptedArgs(buff ,  datap)  (buff,  MSG_CPI_SET_SPEED,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->goal_speed  ) 
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#deliiie  CreateMsgCPISetSpeed(buff ,  datap)  \ 
sprintf  MsgCPISetSpeadArgs(buff ,  (datap)) 
#deline  ParseHsgCPISetSpeedCbulf ,  datap)  \ 
sscanf  HsgCPISetSpeedArgs(bull ,  ft(datap)) 


#deiine  MSG_CPI_SET_DIR  "Xf/.d.*/,d:*/.d;*/.d#" 
typedef  struct  { 

int  client_id;  /*  unique  identifier  for  this  client  */ 
int  seq_num;  /*  label  for  this  command  */ 
int  train.id;  /*  simulator  train  number  */ 
int  new.dir;  /*  indicator  of  neu  train  direction  */ 

>  MsgCPISetDir; 

^define  MSG_CPI_SET_DIR_ARGC  4 

#define  MsgCPISetDirArgs(buff ,  datap)  (buff.  MSG_CPI_SET_DIR,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->neH_dir  ) 

#define  CreateM3gCPISetDir(buff ,  datap)  sprintf  MBgCPISetDirArgs(buff ,  (datap)) 
♦define  ParseMsgCPISetDir(buff ,  datap)  sscanf  MsgCPISetDirArgs(buff ,  ft(datap)) 


♦define  MSG_CPI_EHER_STOP  "Xe‘/.d,y,d;*/,d^" 
typedef  struct  { 

int  client_id;  /*  unique  identifier  for  this  client  */ 
int  seq_nura:  /*  label  for  this  command  ♦/ 
int  train.id;  /*  simulator  train  number  */ 

)•  MsgCPIEmerStop; 

♦define  MSG_CPI_EMER_STOP_ARGC  3 

♦define  MsgCPIEmerStopArgs(buff ,  datap)  (buff,  MSG_CPI_EMER_STOP,  \ 
datap->client_id  ,  datap->seq_num  ,  datap->train_id  ) 

♦define  CreateMsgCPIEmerStop(buff ,  datap)  \ 
sprintf  MsgCPIEmerStopArgs(buff ,  (datap)) 

♦define  ParseMsgCPIEmerStop(buff ,  datap)  \ 
sscanf  HsgCPIEmerStopArgs(buff ,  ft(datap)) 


♦define  MSG.CPI.STA.STQP  ••Xsy.d,'/.d:y.d:%d^" 
typedef  struct  {. 

int  client_id;  /*  unique  identifier  for  this  client  */ 
int  seq_num;  /♦  label  for  this  command  ♦/ 
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int  train_id;  /*  simulator  train  number  •/ 
int  neH_val:  /♦  0  to  disable  and  1  to  enable  */ 

>  KsgCPIStaStop; 

#define  MSG_CPr_STA_STOP_ARGC  4 

#dafine  MsgCPIStaStopArgs(buif ,  datap)  (bufl,  MSG_CPI_STA_STOP,  \ 

datap->client_id  ,  datap->seq_num  ,  datap->train_id  ,  datap->neH_val  ) 

tdeline  CreateMsgCPIStaStop(bulf ,  datap)  \ 
sprintf  MsgCPIStaStopArgsCbulf ,  (datap)) 

#define  ParseMsgCPIStaStop(buff ,  datap)  sscanf  MsgCPIStaStopArgs(bulf ,  4(datap)) 


/^,^tiHi^i^^:^m*iHf*ilf¥**il‘********’>i*’***m******’lf****************************’********/ 

/*  Queries  */ 

#define  MSG_CPI_BLOCK_OCC  ■'Xoy.d.'/.di’/.d#" 
typedef  struct  •( 

int  client.id;  /•  unique  identifier  for  this  client  */ 
int  seq_num;  /*  label  for  this  command  */ 
int  block_id;  /•  simulator  block  number  ♦/ 

>  MsgCPIBlockOcc; 

#define  HSG_CPI_BLOCK_OCC_ARGC  3 

#define  MsgCPIBlockOccArgsCbuff ,  datap)  (bufl,  MSG_CPI_BLOCK_OCC,  \ 
datap->client_id  ,  datap- >seq_num  ,  datap->block_id  ) 

tdefine  CreateMsgCPIBlockOcc(buff ,  datap)  \ 
sprintf  MsgCPIBlockOccArgs(bulf ,  (datap)) 

#define  ParseMsgCPIBlockOcc(bufl ,  datap)  \ 
sscanf  MsgCPIBlockOccArgs(bufl,  ft(datap)) 


#deline  MSG_CPI_SWITCH_POSIT  ■■Xw*/.d.y.d:7.d#" 
typedef  struct  •[ 

int  client.id;  /*  unique  identifier  lor  this  client  */ 
int  seq.num;  /•  label  for  this  command  */ 
int  block_id;  /•  simulator  block  number  ♦/ 

}  MsgCPISwitchPosit; 

•define  MSG_CPI_SWITCH_POSIT_ARGC  3 

•define  MsgCPISHitchPositArgs(buff ,  datap)  (buff,  HSG_CPI_SWITCH_POSIT,  \ 
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datap->client_id  ,  datap->seq_num  ,  datap->block_id  ) 


#define  CreateMsgCPISwitchPosit(b’alf ,  datap)  \ 
sprintf  MsgCPISwitchPositArgsCbuff ,  (datap)) 
♦define  ParseMsgCPISoitchPositCbuff ,  datap)  \ 
sscanf  MsgCPISwitch.PoaitArgs(bnll ,  ft(datap)) 


♦define  MSG_CPI_TRAIII_STATUS  "Xt'/.d,y.d;*/,d^" 
typedef  struct  { 

int  client.id;  /*  unique  identifier  for  this  client  ♦/ 
int  seq_num;  /*  label  for  this  command  */ 
int  train.id;  /*  simulator  train  number  •/ 

>  MsgCPITrainStatus; 

♦define  MSG_CPI_TRAIir_STATUS_ARGC  3 

♦define  MsgCPITrainStatusArgs(buff ,  datap)  (buff,  MSG_CPI_TRAIir_STATUS,  \ 
datap->client_id  ,  datap->seq_num  ,  datap->train_id  ) 

♦define  CreateMsgCPITrainStatus(buff ,  datap)  \ 
sprintf  MsgCPITrainStatusArgs(buff ,  (datap)) 

♦define  P2u:seHsgCPITrainStatus(bttff ,  datap)  \ 
sscanf  MsgCPITrainStatusArgs(buff ,  ft(datap)) 


♦define  MSG.CPI_TRAIH_MOTION  ••Xmy,d,*/.d:y.d^" 
typedef  struct  { 

int  client_id;  /*  unique  identifier  for  this  client  ♦/ 
int  seq_num;  /*  label  for  this  command  */ 
int  train.id;  /*  simulator  train  number  ♦/ 

>  MsgCPITrainMotion; 

♦define  MSG_CPI_TRAIH_KOTIOH_ARGC  3 

♦define  HsgCPITrainMotionArgs(buff .  datap)  (buff,  MSG_CPI_TRAII_MOTIOH,  \ 
datap->client_id  ,  datap->seq_num  ,  datap- >train_ id  ) 

♦define  CreateMsgCPITrainMotion(buff ,  datap)  \ 
sprintf  MsgCPITrainMotionArgs(buff ,  (datap)) 

♦define  ParseMsgCPITrainMotion(buff ,  datap)  \ 
sscanf  MsgCPITrainMotionArgs(buff ,  ft(datap)) 
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C.2  aci.c,  Example  Using  the  LLI  Interface 

/*  $RCSfile:  aci.c, v  $  $Revision:  1.1  $  $i.ate:  92/07/17  10:58:20  $  •/ 

/•  aci.c  —  implementation  of  the  Automatic  Control  Interface  of  the  CPI 
R.  Brown  6/91,  based  on  specifications  and  earlier  versions  */ 

#include  <stdio.h>  /»  for  standard  error  and  HULL  •/ 

#include  <sy s/types .h>  /♦  required  for  acisys.h  */ 
tinclude  "cpi.h"  /*  low-level  interface  of  the  CPI  */ 

#include  "aci.h"  /♦  for  data  type  definitions  ♦/ 

#include  "acisys.h"  /♦  operating  system-specific  routines  */ 

#define  BUFFSIZE  200  /*  maximum  size  of  a  message  */ 

#define  RETRY_IHTERVAL  5.0  /♦  seconds  between  retries  for  ConnectToSim  ♦/ 

^define  QUERY.TIMEOUT  5.0  /•  seconds  before  giving  up  on  a  query  response  ♦/ 

tdefine  EPSILON  0.0001  /*  tolerance  for  floating  point  comparisons  ♦/ 

LayoutData  layout.data,  ♦Idp  =  ftlay out .data; 

/*  data  structure  for  storing  the  information  passed  in  the  download  ♦/ 
int  chan;  /♦  socket  for  communicating  with  simulator  */ 
int  client. id;  /•  identifier  fox  this  client,  obtained  from  simulator*/ 
int  seq.num  =0;  /*  sequence  number,  for  voting  purposes  */ 


/*«;tr:*«*4>«***4i«******««*#«4i***lti4i*«e*ei«i**««***«*Ilce**«**««  ******««****•»•  *«***«/ 

/♦  SendInitMessage  sends  the  simulator  the  initialization  message  lor  this 
application.  Returns  nonzero  on  success,  zero  on  failure. 

RAB  11/30/89  */ 


int 

SendInitMessage(chan,  string) 

int  chan;  /*  channel  descriptor  for  communication  with  simulator  */ 
char  stringC];  /♦  string  to  send  as  part  of  the  message  to  sim  */ 

{ 

char  buff [BUFFSIZE] ;  /♦  buffer  lor  init  message  and  ack  */ 
int  n;  /♦  length  of  received  init  message  •/ 

char  client.id.string [BUFFSIZE] ;  /♦  string  representing  client.id  */ 

/♦  send  the  initialization  message  •/ 
sprint! (buff ,  MSG.CPI.IIIT,  string); 
if  (SendMsgCchan,  buff,  strlcn(bufl))  <  0)  ■( 
perror( "SendInitMessage:  SendHsg  failed"); 
return  (0) ; 


8.3 


} 


/*  wait  for,  verify  acknowledgement  ♦/ 
if  ((n=KecvMsg(chan,  buff,  BUFFSIZE))  <  0)  { 
perron ("SendlnitMessage:  can't  receive  acknowledgement"); 
return  (0) ; 

> 

buffCn]  =  ’\0': 

if  (sscanf (buff ,  MSG.ACK,  client_id_string)  !=  1)  { 

fprintf (stderr ,  "SendInitMessage:  expected  ack,  received  \‘"/.s\"\n‘' ,  buff); 
return  (0); 

} 

sscanf  (client_id_atring,  '“/,d",  *clieat_id);  /♦  extract  unique  id  */ 
return  (1) ; 

} 


/iti*«**«*«««««**iti«e«««iti«*««*«4i«**e4i**e*«*********««**»*«***»***  «*«*****  *«*«**/ 

/• 

We  trust  the  simulator’s  download...  */ 

LayoutData  * 

GetDownload (hostname,  simnum,  progname,  timeout) 

char  ^hostname;  /*  machine  running  a  simulation  */ 
int  simnum;  f*  identifies  a  running  simulation  */ 
char  fprogname;  /*  name  of  invoking  program  */ 
double  timeout;  /*  in  seconds  •/ 

< 

static  GetDownloadSucceeded  =  0;  /♦  set  non-zero  on  first  successful  call  */ 

char  buff [BUTFSIZE] ;  /*  buffer  for  holding  one  message  */ 

union  { 

MsgCPIDownldGeneral  gen;  /*  for  unpacking  message  of  general  attributes  */ 

MsgCPIDownldBlock  block;  /•  for  unpacking  messeige  of  block  attributes  */ 

MsgCPIDownldLink  link;  /•  for  unpacking  message  of  block  attachments  •/ 

MsgCPIDownldTrain  train;  /•  for  unpacking  message  of  train  attributes  */ 

int  val;  /*  for  receiving  integer  value  passed  with  MsgCPIDownldDone  */ 

}  msg; 

int  incomplete;  /*  non-zero  if  the  download  is  found  to  be  incomplete  */ 
int  recv_msg_status;  /*  return  value  from  RecvMsg  */ 
int  i;  /♦  loop  control  •/ 
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if  (GetDownloadSucceeded)  { 

Iprintl (stderr,  "GetDownload  has  already  been  called  successfullyXn") ; 
return  (HULL) ; 

} 

/*  there  have  been  no  prior  successful  calls  */ 
if  (timeout  <=  0)  { 

fprintf (stderr,  "GetDownload:  Non-positive  timeout  '/,.lf\n",  timeout); 
return  (NULL); 

} 

/*  valid  timeout  vas  specified  ♦/ 

if  (!*bostname)  { 

GetLocalHost (buff ,  sizeof (buff ) ) ; 
hostname  =  buff; 

} 

while  ((chan  =  ConnectToSim(hostname,  simnum))  ==  -1)  { 
timeout  -=  RETRY.IHTERVAL; 
if  (timeout  <  EPSILOH)  { 

fprintf (stderr,  "GetDownload:  Could  not  connect  to  simulator \n" ) ; 
return  (HULL); 

>  else  { 

fprintf ("  retrying. . An"): 

Sleep(RETRY_IHTERVAL) ; 

} 

} 

/♦  a  connection  to  the  desired  simulation  has  been  established  ■»/ 

if  ( !SendInitMessage(chan,  progname))  { 
fprintf (stderr ,  "GetDownload:  Could  not  send  init  message\n"); 
CloseChan( chan) ; 
return  (HULL) ; 

> 

/*  CPI  initialization  message  has  been  sent  and  acknowledged  <•>/ 

CreateHsgCPIDownldRequest (buff ,  progname ) ; 
if  (SendMsg(chan,  buff,  8trlen(buff ))  <  0  )  { 
perroT("MsgCPIDownldRequest  SendHsg  failed"); 

fprintf (stderr ,  "GetDownload:  Could  not  send  request  for  dosnload\n") ; 
CloseChan(chan) ; 
return  (HULL): 

} 
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/*  Download  has  been  requested. 

The  simulator’s  expected  response  is  the  download  itself. 


/*  receive  download  ♦/ 

/*  inveir:  all  CPIDownld  messages  so  far  have  been  parsed  */ 
while  ((recv_msg_status  =  RecvDownldHsgCchan,  buff,  BUFFSIZE))  >  0  44 
PaxseMsgCPIDownldDone(buff ,  msg.val)  != 

MSG_CPI_DOWKLD_DDNE_ARGC)  i 

/*  new  message  of  length  recv_msg_status  that  is  not  DownldDone 
has  been  received  */ 

buf f Crecv_msg_status]  =  ’\0’; 

if  (ParseMsgCPIDownldGeneralCbuff ,  4msg.gen)  == 

MSG_CPI_DOHSLD_GEHERAL_ARGC)  { 
ldp->block_ct  =  msg.gen.block_ct; 
ldp->train_ct  =  msg. gen. train. ct; 
ldp->acc  =  msg.gen.acc; 
ldp->emer_acc  =  msg.gen.emer.acc; 
ldp->switch_timo  =  msg.gen.switch.time; 
ldp->voting_quorum  =  msg.gen.voting.quoriua; 
ldp->voting_window  =  msg. gen. voting. window; 

if  (ldp->block_ct  >  MAX.BLOCKS  1 1  ldp->train_ct  >  MAX.TRAIHS)  { 
fprintf (stderr, 

"GetDownload;  MAX.TRAIHS  (7.d)  or  MAX.BLOCKS  C/.d)  too  small\n" , 
MAX.TRAINS ,  MAX.BLOCKS ) ; 
return  (HULL); 

} 

>  else  if  (ParseMsgCPIDownldBleck(buff ,  4msg. block)  == 
MSG.CPI_DOWHLD.BLOCK.ARGC)  { 
int  index  =  msg .  block .  block.id  -  1 ; 

/*  this  block’s  index  in  ldp->blocksD  ♦/ 

ldp->blocks [index] .block.id  =  msg. block. block.id; 
ldp->blocks [index] .length  =  msg. block. length; 
ldp->blocks [index] .type  =  (enum  BlockType)  msg. block. type; 
ldp->blocks [index] .max.speed  =  msg. block. max. speed; 
ldp->blocks [index] .min.speed  =  msg. block. min. speed; 
if  ((enum  BlockType)  msg. block. type  ==  BT.STATIOH) 
ldp->blocks [index] .t.st.sta.stop.speed  =  msg. block. sta.stop.speed; 
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if  ((enum  BlockType)  msg. block. type  ==  BT_CR0SS) 

Idp- >blocks [index] .t. cr. cross_id  =  msg. block. cross.id; 

}  else  if  (PaxseHsgCPIDoBnldLink(buf f ,  tosg.link)  == 
MSG_CPI_DOWHLD_LIIIK_ARGC)  { 
int  index  =  msg. link. block_id  -  1; 

/*  this  block’s  index  in  ldp->blocks []  */ 

switch  (ldp->blocks [index] .type)  { 
case  BT_REGULAR: 
case  BT.STATION; 
case  BT.CROSS: 

ldp->blocks [index] .t.rg. tail  =  msg. link. tail; 
ldp->blocksCindex] .t .rg.bead  =  msg. link. headl; 
break; 

case  BT_J0IN: 

Idp- >blocks [index] .t.jn. tail  =  msg. link. tail; 
ldp->blocks [index] .t.jn. headl  =  msg. link. headl; 

Idp- >blocks [index] .t. jn.head2  =  msg . link . head2 ; 
break; 

case  BT.SWITCH: 

ldp->blocks [index] .t.sw. tail  =  msg. link. tail; 
ldp->blocks [index] .t.sw. straight  =  msg. link. headl; 
ldp->blocks [index] .t.sw. turn  =  msg. link. head2; 
break; 

} 

}  else  if  (ParseMsgCPIDownldTrain(buff ,  ftmsg. train)  == 
HSG_CPI_DOHNLD_TRAI!l_ARGC)  < 
int  index  =  msg. block. block_id  -  1; 

/*  this  train’s  index  in  ldp->trainsn  ♦/ 

ldp->trains [index] .train_id  =  msg. train. train_id; 
ldp->trains [index] .length  =  msg. train. length; 
ldp->trainsCindex] .head. block  =  msg. train. head_block; 
ldp->trains [index] .head. off set  =  msg. train. head.off set; 
ldp->trains [index] .tail. block  =  msg. train. tail_block; 
ldp->trains [index] .tail. offset  =  msg. train. tail.off set; 

}■  else  {  /*  u^ecognized  message  format  */ 

fprintf (stderr,  "GetDownload;  Unrecognized  message  from  simulatorXn") ; 
fprintf (stderr,  "'/,s\n",  buff); 
return  (HULL) ; 

} 
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} 


if  (recv_msg_status  <=  0)  { 

fprintf (stderr,  "GetDownload:  Failed  in  attempt  to  receive  a  messageXn") ; 
return  (NULL); 

> 

/*  There  were  no  failures  to  receive  a  message,  and 

all  received  messages  have  been  successfully  parsed  and  data  stored  in 
layout.data,  and  one  Done  message  nas  received  */ 


/*  check  to  see  whether  download  was  complete  */ 
incomplete  =  0; 

/*  we  will  assume  that  all  of  the  fields  from  HsgCPIDownldGeneral  wero 
received  and  stored  properly  in  layout_data  if  block_ct  is  nonzero  */ 
if  ( lldp->block_ct)  { 

fprintf (stderr,  "GetDownload:  incomplete  download  (missing  General)\n") ; 
incomplete++; 

> 

for  (i  =  0;  i  <  ldp->block_ct;  i++)  { 

/♦  we  will  assume  that  all  of  the  fields  from  HsgCPIDownloadBlock  were 
received  and  stored  properly  in  layout.data  if  block.id  is  nonzero  */ 
if  (!ldp->blocksCi] .block_id)  { 

fprintf  (stderr ,  "GetDownload;  incomplete  download  (missing  Block  ’/,d)\n" 

i  +  1): 

incomplete++; 

} 

/♦  we  will  assume  that  all  of  the  fields  from  MsgCPIDownloadLink  wera 
received  and  stored  properly  in  layout_data  if  tail  is  nonzero  */ 
if  (!ldp->blocksCi] .t.rg.tail)  < 

fprintf  (stderr,  "GetDownload:  incomplete  download  (missing  Link  ’/,d)\n", 

i  +  1) ; 

incomplete++; 

} 

> 

for  (i=0;  i  <  ldp->train_ct;  i++) 

/♦  we  will  assume  that  all  of  the  fields  from  HsgCPIDownloadTrain  were 
received  and  stored  properly  in  layout.data  if  train_id  is  nonzero  */ 
if  (!ldp->trainsCi] .train.id)  { 

fprintf  (stderr,  "GetDownload;  incomplete  download  (missing  Train  '/(d)\n" 
i  +  1): 
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iiicomplete++: 


> 


if  (incomplete) 
return  (NULL); 

/*  a  complete  doonload  was  successfully  received  */ 

GetDownloadSucceeded++ ; 
return  (ftlayout_data) ; 


/*  commands  */ 
void 

SatSwitch(block_id,  new.posit) 
int  block. id; 
enum  NewPosit  new.posit; 

{ 

MsgCPISetSwitch  msg;  /*  data  structure  for  message  construction  •/ 
char  buff [BUFFSIZE] ;  /*  buffer  for  outgoing  message  */ 

msg. client.id  =  client.id;  /*  identifier  of  this  client  ♦/ 
msg.seq.num  =  seq.num;  /♦  voting  sequence  niunber  */ 
msg.block.id  =  block.id; 
msg.new.posit  =  (int)  uew.posit; 

CreateMsgCPISetSwitch(buff ,  ftrasg) ; 
if  (Sendl!sg(chan,  buff,  strlen(buff ))  <  0)  { 
perror('‘SetSwitch:  SendHsg  failed"): 

> 


void 

Accelerate(train_id,  duration) 
int  train. id; 
double  duration; 

{ 

MsgCPIAccel  msg;  /♦  data  structure  for  message  construction  ♦/ 
char  buf  f  [BUFF.SIZE]  ;  /♦  differ  for  outgoing  message  ♦/ 


89 


msg.client_id  =  client_id;  /•  identiiier  of  this  client  */ 
msg.seq_num  =  seq.num;  /♦  voting  sequence  nuaber  ♦/ 
msg.train_id  =  train.id; 
msg. duration  =  duration; 

CreateMsgCPIAccel(buff ,  tosg); 
if  (SendHsg(chan,  buff,  strlen(buff ))  <  0)  { 
perrorC'Accelerate;  SendMsg  failed"); 

} 


void 

Decelerate(train_id,  duration) 
int  train, id; 
double  duration; 

MsgCPIDecel  msg;  /*  data  structure  for  message  construction  ♦/ 
char  buff [BUFFS I ZE] ;  /*  buffer  for  outgoing  message  »/ 

msg.client.id  =  client.id;  /*  identifier  of  this  client  */ 
msg.seq.num  =  seq.mun;  /*  voting  sequence  number 
msg.train.id  =  train.id; 
msg. duration  «  duration; 

CreateMsgCPlDeceKbuff ,  ftnsg); 
if  (SendMsg(chan,  buff,  strlen(buff ))  <  0)  { 
perrorC'Decelerate :  SendMsg  failed"); 

> 


void 

SetSpeed(train_id,  goal.speed) 
int  train.id; 
double  goal_speed; 

{ 

HsgCPISetSpeed  msg;  /*  data  structure  for  message  construction  */ 
char  buff [BUFF SIZE] ;  /*  buffer  for  outgoing  message  */ 

msg. client_id  =  cliant_id;  /*  identifier  of  this  client  */ 
msg.seq,num  =  seq_num;  /♦  voting  sequence  number  */ 
msg.train_id  =  train.id; 
msg.goal_speed  =  goal_speod; 
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CreateMsgCPISetSpecd(bufl ,  ftmsg) ; 
if  (SendMsgCchan,  buff,  strlen(buff ) )  <  0)  ■( 
perrorC’SetSpeed:  SendMsg  failed"): 

> 


void 

SetDirection(train_id,  nev.dir) 
int  train.id; 
int  new_dir: 

MsgCPISetDir  msg;  /*  data  structure  for  message  construction  •/ 
char  buff CBUFFSIZE] :  /♦  buffer  for  outgoing  message  •/ 

msg . client.id  =  client_id;  /*  identifier  of  this  client  ♦/ 
msg.seq.num  =  seq_num;  /•  voting  sequence  number  */ 
msg.train.id  =  train_id; 
msg.neu.dir  =  neu.dir; 

CreateHsgCPISetDirCbuff ,  Amsg); 
if  (SendHsg(chau,  buff,  strlen(buff ) )  <  0)  •{ 
perrorC'SetDirection;  SendMsg  failed"); 

} 


void 

EmergencyStop(train_id) 
int  train_id: 

{ 

MsgCPIEmerStop  msg;  /*  data  structure  for  message  construction  */ 
char  buf f [BUFFSIZE] ;  /♦  buffer  for  outgoing  message  •/ 

msg.client_id  =  client_id;  /♦  identifier  of  this  client  ♦/ 
msg.seq_num  =  seq.num;  /*  voting  sequence  number  •/ 
msg.train.id  =  train.id; 

CreateMsgCPIEmerStop(buff ,  ftmsg) ; 
if  (SendMsg(chan,  buff,  8trlen(buff ))  <  0)  { 
perrorC'EmergencvStop;  SendMsg  failed"); 

> 
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void 

StationStop(train_id,  n«»_val) 
int  train. id; 

enuin  StationStopMode  netr.val; 


MsgCPIStaStop  msg:  /*  data  structure  for  message  construction  •/ 
char  bull [BUFFSIZE] ;  /*  buller  lor  outgoing  message  */ 

msg.client.id  =  cliont.id;  /*  identilier  ol  this  client  */ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  */ 
msg.train.id  =  train.id; 
mag.new.val  =  (int)  neu.val; 

CreateMsgCPIStaStopCbull,  ftmsg); 
il  (SendMsg(chan,  bull,  strlen(bull))  <  0)  { 
perrorC'StationStop:  SendMsg  lailed"); 

} 


/*  Queries  */ 


enum  Occupancy 
GetBlockOccupancy (block.id) 
int  block. id; 

{ 

MsgCPIBlockOcc  msg;  /*  data  structure  lor  message  construction  */ 
char  bull [BUFFS I ZE] ;  /*  buller  lor  outgoing  message  */ 

int  n;  /*  return  status  Irom  RecvMsgTimed  */ 

msg. client. id  =  client.id;  /♦  identilier  ol  this  client  */ 
msg.seq.num  =  seq.num;  /*  voting  sequence  number  */ 
msg.block.id  =  block. id; 

CreateMsgCPIBlockOcc(bull ,  kmsg) ; 
il  (SendMsg (chan,  bull,  strlen(bull) )  <  0)  { 
perror("GetBlockOccupancy :  SendMsg  lailed"): 

} 
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±1  ((n  =  RecvMsgTimedCchan,  buff,  BUFFSIZE,  QUERY.TIMEOUT) )  <  0) 
return  (QC_ERROR) ; 

/*  response  successfully  received  from  simulator  and  stored  in  buff  •/ 

switch  (buff Co])  < 
case  ’o’:  return  (OC.OCCUPIED) ; 
case  ’f’:  return  (QC.FREE); 
default : 

buff [n]  =  ’ \0 ’ ; 

fprintf  (stderr,  "GetBlockOccupancy ;  unknown  simulator  response  \'‘'/.s\’'\n" , 
buff); 

return  (OC.ERROR) ; 

} 

> 


enum  SoitchPosit 
GetSHitchPosition(block_id) 
int  block_id; 

{ 

MsgCPISsitchPosit  msg;  /•  data  structure  for  message  construction  •/ 
char  buff [BUFFSIZE] ;  /•  buffer  for  outgoing  message  */ 

int  n;  /*  return  status  from  RecvMsgTimed  */ 

msg.client.id  =  client.id;  /*  identifier  of  this  client  */ 
msg.seq.num  =  seq_num;  /*  voting  sequence  number  •/ 
msg .block, id  =  block, id; 

CreateKsgCPISwitchPosit(buff ,  ftmsg) ; 
if  (SendHsgCchan,  buff,  strlenCbuf f ) )  <  0)  < 
porrorCGetSwitchPosition:  SendMsg  failed"); 

} 

if  ((n  =  RecvMsgTimed(chan.  buff,  BUFFSIZE,  QUERY.TIMEOUT))  <  0) 
return  (SP_ERR0R); 

/♦  response  successfully  received  from  simulator  euid  stored  in  buff  •/ 

switch  (buff Co])  { 

case  ’s’:  return  (SP.STRAIGHT) ; 

case  ’t’:  return  (SP_TURSED); 

case  ’u’:  return  (SP.UHDEFIHED) ; 

default: 

buffCn]  =  ’\0’; 

fprintf  (stderr.  "GetSwitchPosition:  unknown  simulator  response  \''/,s\"\n”. 
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bulf ); 

return  (SP.ERRQR); 

} 


enum  TrainStatus 
GetTrainStatus (train_id) 
int  train_id; 

■C 

MsgCPITrainStatus  msg;  /•  data  structure  for  message  construction  ♦/ 
char  bufi [BUFFSIZE] ;  /•  buffer  for  outgoing  message  */ 

int  n;  /•  return  status  from  RecvMsgTimed  ♦/ 

msg. client.id  =  client.id;  /*  identifier  of  this  client  */ 
msg.seq_num  =  seq_num;  /♦  voting  sequence  number  •/ 
msg.train.id  =  train.id; 

CreateMsgCPITrainStatus (buff ,  4msg) ; 
if  (SendMsgCchan,  buff,  strlen(buff ))  <  0)  { 
perror("GetTrainStatus:  SendMsg  failed"); 

} 

if  ((n  =  RecvMsgTimed(chan,  buff,  BUFFSIZE,  QUERY.TIMEOUT) )  <  0) 
return  (TS.ERROR); 

/♦  response  successfully  received  from  simulator  and  stored  in  buff  •/ 

snitch  (buff [0] )  { 

case  ’c’;  return  (TS.CRASHED) ; 

case  ’r':  return  (TS_RUHIIIG) ; 

default; 

buffCn]  =  ’\0’: 

fprintf (stderr,  "GetTrainStatus:  unknonn  simulator  response  \"*/,s\"\n", 
buff); 

return  (TS.ERROR) ; 

} 


enum  TrainMotion 
GetTrainJ!otion(train_id) 
int  train_id; 

MsgCPITrainMotion  msg;  /*  data  structure  for  message  construction  */ 
char  buff [BUFFSIZE] ;  /*  buffer  for  outgoing  message  •/ 
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int  n;  /♦  return  status  Irom  RecvMsgTimed  *f 

msg.client.id  =  cliont_id;  /♦  identifier  of  this  client  •/ 
msg. seq.num  =  seq_num;  /•  voting  sequence  number  */ 
msg. train. id  =  train, id; 

CreateMsgCPITrainMotionCbuff ,  liasg) ; 
if  (SendMsg(chan,  buff,  strlen{buff ))  <  0)  { 
perrorC'GetTrainMotion;  SendMsg  failed"); 

> 

if  ((n  =  RecvMsgTimedCchan,  buff,  BUFFSIZE,  QUERY.TIMEOUT) )  <  0) 
return  (TM.ERRQR) ; 

/♦  response  successfully  received  from  simulator  and  stored  in  buff  •/ 

snitch  (buff[0])  { 
case  's':  return  (TM.STQPPED) ; 
case  'm';  return  (TM.MOVIHG); 
def  ault ; 

buff[n]  =  '\0’; 

fprintf  (stderr ,  "GetTrainMotion:  unknonn  simulator  response  \"*/,s\"\n", 
buff); 

return  (TM.ERROR); 

> 


/•  Voting  Sequence  Humber  */ 
int 

SetSeqNuraber(ns<»_val) 
int  new.val; 

{ 

if  (new.val  <  0) 
ret\irn  (-1); 
else  i 

seq.num  =  nen.val; 
return  (seq.num); 

} 

} 


int 
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HewSeqHvunberO 

i 

return  (+-t-seq_nuja)  ; 

> 
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Reference  Pages 


acitest(l ) 
ts(l)  .  . 
tsed(l)  ,  . 
tsim(l)  .  . 
t jpanel(] ) 
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Ncune 

acitest  -  manual  test  of  CPI  interface  in  Trains et 
Syntax 

acitest  C  -d  ]  [  simhost  [  simnum  ]] 

Description 

acitest  is  an  example  program  included  with  the  Trainset 
software.  Its  source  code  illustrates  the  use  of  the  upper 
layer  (called  the  ACI)  of  the  Control  Program  Interface 
(CPI).  When  invoked  and  connected  to  a  running  railroad 
simulation  (see  tsim(l)),  it  enables  a  user  to  interactively 
perform  each  ACI  command  and  query.  The  effects  of  each 
action  may  be  observed  using  the  monitor  programs  tspanel(l) 
and  tsviewd) . 

Options  and  Arguments 

-d  Causes  the  state  information  received  from  a  simulation 
to  be  printed  during  startup. 

simhost 

Specifies  the  name  of  a  host  that  is  running  a  simula¬ 
tion  of  a  railroad.  If  an  empty  string  is  specified, 
the  local  host  is  used.  If  the  simhost  argument  is 
omitted,  a  value  is  requested  interactively. 

simnum 

An  integer  that  determines  which  invocation  of  the  tsim 
simulator  (at  the  indicated  host)  is  to  be  used.  The 
default  value  is  0.  The  monitor  programs  and  the 
desired  invocation  of  tsim  should  use  the  same  value 
for  number. 

See  Also 

ts(l),  tsim(l),  tspanel(l),  tsviewd). 
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Haiae 

ts  -  launch  Trainset  applications 
Syntax 

ts  [  flags . . .  ] 

ts  -edit  C  file  ]  [  -layout  file  3  [  -tsroot  dir  ]  [  Xll- 
options  ] 

Description 

ts  invokes  ('‘launches’’)  applications  related  to  the  Train- 
set  railroad  simulation  software  in  a  computing  environment 
that  may  involve  a  heterogeneous  network  of  computing  sys¬ 
tems.  With  no  options,  ts  typically  starts  a  demonstration 
consisting  of  a  simulation  of  a  sample  railroad,  an  Xll 
application  that  graphically  displays  the  current  state  of 
the  railroad,  and  another  Xll  application  that  provides  for 
manual  control  of  the  railroad,  ts  options  enable  the  user 
to  select  which  applications  axe  to  be  launched,  choose  the 
railroad  layout  to  be  simulated,  specify  the  host  to  launch 
from,  etc. 

Programmers  may  write  software  that  interacts  with  Trainset, 
including  programs  that  automatically  control  a  railroad  and 
custom  versions  of  the  basic  Trainset  software,  ts  provides 
a  configuration  mechanism  for  adding  launch  information 
describing  such  programs  to  its  database. 

When  invoked  with  -edit  as  the  first  command-line  option,  ts 
invokes  the  tsed  editor  for  railroad  layouts  and  launches  no 
other  applications.  The  options  -tsroot  and  -layout  are 
recognized  by  ts  in  the  case  of  -edit ,  aind  may  appeair  either 
in  an  environment  variable  TSOPTS  or  on  the  command  line . 
file  names  the  layout  data  file  to  be  edited,  file  may  be 
presented  as  the  second  command  line  argument  if  it  does  not 
begin  with  a  dash  It  may  also  be  provided  using  the 

-layout  option,  -tsroot  specifies  the  tsed  search  paths  for 
layout  data  files,  as  discussed  in  Search  Paths  below.  In 
addition,  any  additional  options  on  the  command  line,  in 


99 


particular  options  recognized  by  Xll,  are  passed  on  to  tsed. 
Applications 

Trainset  consists  of  application  programs  that  support 
interaction  with  a  simulated  railroad.  Railroads  are 
represented  by  layouts  that  consist  of  trains  and  blocks  of 
track.  Users  of  Trainset  may  urite  programs  that  use  the 
Control  Program  Interface  (CPI)  to  control  such  a  railroad. 
For  more  information,  see  the  manuals  for  Trainset. 

The  standard  applications  that  comprise  Trainset  include  the 
following. 

tsim  Simulator  of  railroad  layouts. 

tsed  Editor  for  interactive  creation  and  modifica¬ 

tion  of  a  layout. 

tsview  A  graphical  display  of  the  state  of  a  layout 

during  a  simulation. 

tspanel  A  graphical  control  panel  for  meinually 

operating  a  layout’s  trains  and  switch 
blocks . 

In  addition,  programs  that  demonstrate  the  CPI,  including 
acitest  and  demo,  are  provided  in  the  Trainset  distribution. 

Control  Codes 

In  ts,  applications  are  referenced  by  control  codes  that  aire 
strings  consisting  of  an  uppercase  letter  optionally  fol¬ 
lowed  by  ary  combination  of  lowercase  letters,  digits, 
underscoTjs  and  periods.  The  following  control  codes  are 
conventionally  defined  in  the  main  configuration  file  for 
ts: 

Sim,  S,  Tsim  Trainset  railroad  simulator. 


ts(l) 


Panel,  P,  Tspanel 

Control  panel  application. 

Viewer,  V,  Tsview 

Viewer  application  lor  observing  a  simula¬ 
tion  . 

A.citest,  A  Acitest  program  that  allows  manual  experimen¬ 
tation  with  CPI  interface  features. 

Demo,  D  Demonstration  of  the  CPI  interface  discussed 

in  the  Trainset  manual. 

Any  of  the  ts  options  -args,  -delay,  -direct,  -display, 

-host ,  -tsroot ,  -xtorm  and  -xtermargs  can  be  localized  to 
apply  to  a  specific  application  by  prefixing  that  option 
with  the  appropriate  control  code(s).  For  example,  either 
‘Sim;-host  loki’  or  ‘S:-host  loki’  specifies  that  the  simu¬ 
lator  should  be  launched  at  the  site  loki.  Also, 
‘PV:-display  thorrO.O’  causes  the  panel  and  viewer  applica¬ 
tions  to  display  graphics  output  on  the  Xll  server  thor:0.0. 
Arbitrary  arguments  can  be  passed  to  applications  using  the 
-args  option  prefixed  by  the  appropriate  control  code,  e.g., 
‘Myprog :-args  "-level  4  -trace"’.  Quoting  (e.g.,  using 
enables  spaces  to  be  included  in  the  argument  string. 

If  the  colon  that  terminates  a  prefix  is  followed  immedi¬ 
ately  by  a  character  (e.g.,  dash  ‘-’)  that  cannot  be  part  of 
a  control  code  name,  then  that  colon  may  be  omitted.  For 
example,  ‘Sim-host  loki’  is  equivalent  to  ‘Sim:-host  loki’. 

An  alias  facility  is  provided  for  associating  multiple  con¬ 
trol  codes  with  a  single  application.  Aliases  may  be 
declared  in  configuration  files  (discussed  below)  or  by 
using  the  -alias  option.  The  alias  feature  can  be  used  to 
change  the  associations  between  control  codes  and  applica¬ 
tions.  For  example,  suppose  that  a  control  code 
Train_control_2  is  associated  with  an  application  that  has 
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been  written  locally.  Then  the  ts  option  ‘-alias 
T=Train_control_2’  assigns  the  control  code  T  to  represent 
that  local  application.  Train_control_2  is  a  better  identif¬ 
ier,  but  the  alias  T  is  more  convenient  as  a  prefix.  Also, 
‘-alias  Demo=T’  could  be  used  to  associate  the  control  code 
Demo  with  that  local  application  instead  of  the  stand^lrd 
Trainset  demonstration  program. 

The  -dup  option  may  be  used  to  invoke  multiple  copies  of  am 
application.  This  feature  supports  the  launching  of  repli¬ 
cated  programs,  -dup  clones  the  launch  information  gathered 
so  far  lor  the  application  in  question  and  associates  a  con¬ 
trol  code  with  the  copy.  The  launch  attributes  in  the  two 
copies  may  thereafter  be  modified  independently. 

Search  Paths 

The  directory  tsroot  identifies  the  location  of  the  Trainset 
installation  in  the  local  file  system.  Tsroot  may  be  speci¬ 
fied  as  the  value  of  an  environment  variable  TSROOT  or  on 
the  command  line  using  the  -tsroot  option. 

Ts  searches  for  its  own  configuration  files  in  the  direc¬ 
tories  .,  ./lib,  tsroot  amd  tsroot/lib  (in  that  order). 

Layout  data  files  lor  a  simulation  are  sought  in  the  direc¬ 
tories  ./layouts,  tsroot,  tsroot/layouts  and 
tsroot/trainset/layouts .  The  default  extension  is 
appended  (if  omitted)  to  a  layout  data  file  name  by  Trainset 
applications  and  seetrching  is  repeated  if  a  file  with  the 
given  name  was  not  found.  If  no  layout  data  file  is  speci¬ 
fied,  the  file  tsroot/layouts/seutple.l  is  used. 

Binaries  for  Trainset  applications  are  sought  using  the 
environment  variable  PATH  as  usual. 

Launching  Applications 

Unless  the  -edit  option  is  specified,  ts  gathers  information 
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from  the  following  sources,  in  order,  before  launching 

applications . 

Main  configuration  file 

This  file  associates  control  codes  with  applications, 
contains  invocation  information  for  applications  (e.g., 
name  of  executable  and  default  arguments)  and  provides 
a  default  list  of  applications  to  be  launched.  See 
ts.config(5)  for  the  file  format.  The  name  of  the  main 
configuration  file  may  be  specified  with  the  -config 
option.  The  default  main  conf igiiration  file  is 
tsroot/ts . config . 

Axixiliary  configuration  files 

One  or  more  additional  configuration  files  may  be 
designated  to  supplement  the  main  configuration  file. 
These  are  specified  by  the  ts  options  -confign  where  n 
is  a  single  digit.  Auxiliary  configuration  files  are 
processed  in  increasing  order  of  n.  The  values  of  n 
need  not  be  contiguous.  Auxiliary  configuration  files 
enable  individual  users  and  groups  of  users  to  install 
their  own  applications  and  customize  launching  informa¬ 
tion  for  applications  that  appear  in  the  main  confi¬ 
guration  file.  Attributes  for  the  launch  are  either 
overridden  or  appended  as  appropriate.  If  a  non-empty 
list  of  applications  to  be  launched  is  included  in  an 
auxiliary  configuration  file,  it  overrides  any  prior 
list .  There  are  no  default  auxiliary  configuration 
files . 

Environment  variables  TSROOT,  TSOPTS  and  DISPLAY 

If  there  is  an  environment  variable  TSROQT,  it  is 
treated  as  the  default  value  for  tsroot  (see  Search 
Paths  above).  If  there  is  an  environment  variable 
TSOPTS,  it  is  treated  as  a  list  of  ts  options  that  are 
parsed  prior  to  the  options  specified  on  the  command 
line.  If  there  is  an  environment  variable  DISPLAY  with 
value  Xll-display,  then  the  option  -xtermargc  XI 1- 
display  is  implicitly  processed  just  prior  to  any 
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options  in  TSOPTS. 

Command  line  options 

See  Options  belos. 

The  significance  of  the  ordering  above  is  that  later  values 
override  or  are  appended  to  earlier  values.  For  example,  a 
-host  option  in  TSOPTS  overrides  any  HOST  entries  in  confi¬ 
guration  files,  and  ‘Sim;-args  "-uindov  5"’  on  the  command 
line  appends  to  the  arguments  for  the  Sim  application  that 
sere  collected  from  configuration  files  and  TSOPTS. 

Launching  at  a  remote  host  is  accomplished  by  invoking  ts  at 
the  remote  site,  as  described  in  ts .remote(8) .  The 
information  that  is  passed  to  a  remote  ts  consists  of  ctn 
options  list  that  is  assembled  by  the  local  ts  after  scan¬ 
ning  the  local  sources  listed  above.  That  options  list  con¬ 
sists  of  the  foliosing. 

A  -launch  option  listing  the  applications  to  bo 
launched  at  that  site. 

A  -display  option,  unless  no  -display  attribute  was 
given  and  there  is  no  local  DISPLAY  environment  vari¬ 
able. 

Any  applicable  control-code  specific  -display  options, 
-simhost  eoid  -simnum  options. 

Any  local  command-line  options  that  remain  after  remov¬ 
ing  -host  and  -launch  (+)  options. 

The  remote  ts  gets  its  launch  information  first  from 
remote-site  configuration  files,  then  from  remote-site 
environment  variables  and  finally  from  the  options  list  that 
Has  assembled  at  the  local  site.  (lote  that  values  for 
attributes  such  as  -delay  and  -tsroot  may  be  passed  to  the 
remote  site  only  if  they  are  specified  in  local  command-line 
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options . ) 

ts  provides  tno  methods  for  launching  applications, 
zterm  Method 

If  the  configuration  file  attribute  XTERM  for  an  appli¬ 
cation  is  a  string  of  positive  length  or  if  the  -xterm 
option  is  used,  then  the  application  is  invoked  in  an 
iterm(l)  HindoH  that  is  created  for  that  purpose.  That 
application’s  8tand2u:d  input  and  output  will  be  associ¬ 
ated  with  the  ztem  window.  Arguments  can  be  passed  to 
zterm  using  the  -ztermargs  option  discussed  below. 

Direct  Method 

Applications  that  are  launched  without  using  the  xterm 
method  are  invoked  asynchronously  by  the  ts  process, 
and  share  that  process’s  standard  output.  The  standard 
input  for  all  such  applications  is  /dev/null,  except 
the  last  application  launched  by  the  direct  method 
inherits  the  ts  process's  standard  input  as  well  as 
standard  output.  Thus,  an  interactive  application 
(e.g.,  acitest(l))  may  be  launched  using  the  direct 
method  provided  that  it  the  last  such  application 
specified.  See  the  Examples  section. 

xterm  is  the  default  launch  method.  The  direct  method  is 
currently  implemented  for  the  local  host  only,  i.e.,  the 
host  at  which  the  ts  command  was  entered.  Thus,  any  -host 
options  are  ignored  for  applications  launched  by  the  direct 
method . 

Options 

-alias  controll=control2 

Declares  the  control  code  controll  to  be  an  alias  for 
the  control  code  control2.  The  two  codes  may  then  be 
used  interchangeably  for  referring  to  the  application 
launch  attributes  associated  with  control2,  if  there  is 
sue’*  an  application.  The  symbol  is  optional. 
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-dup  controll=control2 

Make  a  copy  controll  of  the  application  launch  attri¬ 
butes  associated  vith  control2.  Since  the  tuo  control 
codes  represent  different  copies,  a  change  in  the 
attributes  referenced  by  controll  will  have  no  effect 
on  the  attributes  referenced  by  control2.  This  is  use¬ 
ful  for  invoking  multiple  copies  of  the  same  applica¬ 
tion,  e.g.,  parallel  copies  of  the  same  CPI  program  for 
controlling  a  railroad.  The  symbol  '=’  is  optional. 

-args  arglist 

Provides  program-specific  arguments  to  be  passed  to 
applications.  This  option  is  ordinarily  prefixed  by 
control  codes,  e.g.,  ‘Sim;-args  "-update  O.S"’. 

-config  filename 

Specifies  the  name  of  the  main  configuration  file, 
-confign  filename 

Specifies  the  name  of  the  nth  auxiliary  configuration 
file. 

-delay  seconds 

Specifies  an  integer  number  of  seconds  to  pause  just 
after  launching  each  application. 

-direct 

Specifies  that  applications  should  be  launched  using 
the  direct  method. 

-display  Xll-display 

Indicates  the  display  for  Xll  output.  The  environment 
variable  DISPLAY  is  set  to  Xll-display  for  the  applica¬ 
tions  that  are  launched,  and  '-display  Xll-display’  is 
appended  to  the  list  of  zurguments  for  xterm.  The 
latter  effect  is  approximately  equivalent  to  -xtermairgs 
"-display  Xll-display";  this  does  not  affect  applica¬ 
tions  launched  by  the  direct  method,  but  such  applica- 
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tions  can  still  obtain  the  value  Xll-display  by 
examining  the  environment  variable  DISPLAY. 

-edit  filename 

Invoke  the  tsed  editor  to  create  or  modify  a  layout 
data  file  of  blocks  and  trains  to  be  simulated.  If 
filename  is  a  relative  path  (does  not  begin  with 
a  file  Hith  that  name  is  searched  for  using  the  search 
path  for  layouts.  If  such  a  file  is  found,  its  path  is 
passed  to  tsed  for  modification.  Othersise,  fileneune 
is  passed,  so  that  a  nes  layout  data  file  sith  that 
name  may  be  created  relative  to  the  current  working 
directory.  The  -edit  option  should  not  be  used  in  com¬ 
bination  with  any  other  ts  options. 

-host  hostname 

ts  seeks  configuration  files  and  invokes  executables  at 
the  site  hostname,  except  when  specifically  overridden 
by  other  ts  options. 

-layout  filename 

The  railroad  layout  to  be  simulated  is  described  in 
filename,  which  must  be  in  the  format  produced  by  tsed. 
See  Search  Paths  above. 

-launch  control . . . 

Specifies  that  the  indicated  applications  (only)  should 
be  invoked.  The  default  list  of  applications  to  launch 
is  determined  by  the  first  lines  of  configuration 
files . 

-quorum  n 

Sets  the  simulator  voting  quorum  value  to  n. 

Equivalent  to  ‘Sim'.-axgs  "-quorum  n"  ’ . 

-tsroot  dirname 

Specifies  the  value  of  tsroot. 

-simhost  hostname 
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Specifies  the  host  on  Bhich  to  invoke  the  simulator. 
Equivalent  to  ‘Sim:-host  hostname’. 

-simnum  number 

number  determines  which  well-known  port  is  to  be  used 
when  initializing  communication  with  a  railroad  simula¬ 
tion.  Permissible  values  for  number  are  installation- 
dependent  and  typically  include  the  range  0  to  99. 
Applications  that  axe  launched  with  a  given  value  for 
number  can  only  connect  with  a  simulation  that  was 
launched  with  that  same  -simnum  value  number;  thus, 
multiple  railroad  simulations  may  be  run  simultaneously 
on  the  same  host  if  they  use  different  values  for 
number.  It  is  convenient  to  assign  several  unique 
values  of  number  to  each  Trainset  user  in  order  to 
avoid  collisions  among  users. 

-update  seconds 

Specifies  the  frequency  that  the  simulator  sends  state 
update  reports  to  graphics  monitor  programs  (control 
panel  and  viewer),  seconds  may  be  a  decimal  value, 
e.g.,  0.5.  Equivalent  to  ‘Sim:-args  "-update 
seconds" ’ . 

-window  seconds 

Sets  the  simulator  voting  window  value  to  seconds. 
Equivalent  to  'Sim:-args  "-window  seconds"’. 

-xterm 

Specifies  that  applications  should  bo  launched  using 
the  xterm  method. 

-xtermargs  args 

Provides  arguments  to  be  passed  to  xtorm(l),  for  appli¬ 
cations  to  be  launched  using  the  xterm  method.  Enclose 
args  in  quotes  if  it  contains  embedded  spaces. 

+control. .  . 

Same  as  -launch  control . 
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axgs  Any  options  that  are  not  listed  above  are  passed  to 
ztermd)  for  applications  launched  using  the  xterm 
method.  Thus,  the  options  args  is  approximately 
equivalent  to  -xtermaxgs  "args”. 

Examples 

Start  the  standard  programs  (as  listed  in  in  configuration 
files)  using  their  default  methods.  Use  the  default  layout 
data  file  to  define  the  railroad  being  simulated.  Send  all 
graphics  output  to  the  Xll  server  specified  in  the  environ¬ 
ment  variable  DISPLAY,  and  interpret  any  options  listed  in 
the  environment  variable  TSOPTS. 

ts 


Seek  a  file  oval.l  as  described  in  Search  Paths  above  for 
layout  data  files.  If  it  is  found,  then  start  the  standard 
programs  as  before,  with  the  simulator  tsim  using  that  file 
oval.l  to  define  the  railroad  layout. 


ts  -layout  oval.l 


Start  the  standard  programs  as  before,  except  send  output 
for  the  Peutel  application  to  thor:0  and  send  all  other 
graphics  output  to  the  Xll  server  loki:0.  Send  updated 
information  to  any  running  graphics  monitor  programs  (e.g., 
Viewer  and  Panel)  every  3/4  second. 

ts  -display  loki;0  -update  .76  Panel: "-display  thor:0" 


109 


ts(l) 


Launch  the  applications  S,  V  and  A  using  their  default 
methods.  Unless  these  control  codes  have  been  reassigned, 
they  refer  to  the  Simulator,  Viewer  and  Acitest  applica¬ 
tions  . 


ts  +SVA 


Launch  the  applications  S,  V  and  A  using  the  direct  method. 
Output  for  the  various  applications  will  be  intermingled  on 
the  screen.  Since  A  is  specified  last,  that  application  can 
be  operated  interactively.  The  direct  method  is  useful  for 
debugging  new  applications  and  for  systems  that  do  not  sup¬ 
port  the  program  xterm(l). 

ts  +SVA  -direct 


Bugs 

The  remote  invocation  facility  is  not  currently  implemented. 

Unpredictable  results  may  occur  if  a  control  code  is  made  a 
duplicate  of  itself. 

See  Also 

tsed(l),  tsim(l),  tspanol(l),  tsview(l),  ts . conf ig(5) , 
ts .remote(8) . 
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tsad  -  Trainset  layout  editor 
Syntax 

tsed  C  file  ]  [  -layout  file  ]  [  -tsroot  dir  ]  [  Xll-options 

] 

Description 

tsed  is  an  interactive  graphics  editor  for  defining  etnd 
modifying  railroad  layouts  for  use  in  the  Trainset  railroad 
simulation  softnare.  On  startup,  tsed  displays  two  windows: 
(1)  a  canvas  window  on  which  the  layout  is  created.  The 
window  contains  a  set  of  pulldown  menus  along  the  top,  a 
message  area  at  the  bottom,  and  is  overlaid  with  an  align¬ 
ment  grid,  and  (2)  a  tools  window  consisting  of  icons 
representing  the  operations  available  for  creating  and  modi¬ 
fying  blocks  and  trains . 

With  no  file  or  options  specified,  tsed  starts  with  a  blank 
unnamed  layout.  The  options  -tsroot  and  -layout  are  recog¬ 
nized  by  tsed  and  may  appear  either  in  the  environment  vari¬ 
able  TSOPTS  or  on  the  command  line,  file  names  the  layout 
data  file  to  be  edited,  file  may  be  presented  as  the  second 
command  line  argument  if  it  does  not  begin  with  a  dash 
It  may  also  be  provided  via  the  -layout  option,  -tsroot 
identifies  the  location  of  the  ts  installation  in  the  file 
system  and  is  used  to  determine  the  location  of  auxiliary 
files  needed  by  tsed.  These  are  searched  for  in  tsroot, 
tsroot/lib  and  tsroot/trainset/lib  if  tsroot  is  specified 
and  then  according  to  the  PATH  environment  variable,  tsed 
uses  tsroot  to  search  for  layout  data  files  in  the  following 
order;  .,  ./layouts,  tsroot,  tsroot/layouts  and 
tsroot/trainset/layouts .  The  default  extension  '.1’  is 
appended  to  a  layout  data  file  name  emd  the  search  repeated 
if  the  given  file  was  not  found. 

tsed  also  recognizes  the  stsuidard  XI 1  application  options. 
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Layout  Tools 

The  layout  tools  lie  in  too  coliunns  oJ  icons  in  the  tools 
window  and  are  called  (top  to  bottom,  left  to  right)  Select, 
Erase,  Straight  Block,  Station  Block,  Arc  Block  1,  Arc  Block 
2,  Cross  Block,  Join  Block,  Switch  Block  1,  Switch  Block  ?, 
Train,  and  Rotate.  Select,  Erase,  and  Rotate  manipulate 
existing  blocks.  Straight  Block  amd  Station  Block  create 
linear  blocks.  Arc  Block  1  and  Arc  Block  2  create  circular 
arc  blocks.  Cross  Block,  Join  Block,  Switch  Block  1,  and 
Switch  Block  2  create  fixed  size  iconic  blocks.  The  current 
tool  is  shown  highlighted  by  inverting  its  colors  and  is  set 
by  clicking  on  it .  Clicking  the  left  mouse  button  in  the 
canvas  area  invokes  the  current  layout  tool,  tsed  provides 
the  following  layout  tools; 

Select  Move  block  labels  by  dragging  within  their 

boundaries .  Select  a  block  by  clicking  on  it 
whether  or  not  it's  already  selected  and  dis¬ 
card  any  other  selection. 

Erase  Remove  a  block  or  train  from  a  layout  by 

clicking  on  it. 

The  four  tools.  Straight  Block,  Station  Block,  Arc  Block  1, 
and  Arc  Block  2,  create  regular  and  station  blocks  using  a 
drag  technique  to  determine  the  position  of  the  head  and 
tail  terminators  of  the  block.  If  the  start  point  or  end 
point  of  the  drag  is  within  a  few  pixels  of  the  terminator 
of  an  existing  block,  tsed  attempts  to  establish  a  connec¬ 
tion.  In  such  a  case,  tsed  constrains  the  slope  of  the  new 
block  to  match  the  slope  of  the  existing  block  at  the  termi¬ 
nator  . 

Straight  Block  Create  a  straight  regular  block.  The  block 

is  constrained  to  bo  vertical,  horizontal,  or 
at  +  or  -  45  deg  diagonal . 

Station  Block  Create  a  station  block.  Created  and  con¬ 
strained  in  the  same  way  as  straight  block 
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\bove. 

Arc  Block  1  Create  a  circular  arc  reguleir  block.  The 

start  point  of  a  drag  determines  the  location 
of  the  head  terminator  of  the  block.  The 
radius  of  the  circular  arc  is  two  grid  divi¬ 
sions.  The  extent  of  the  arc  is  determined 
by  the  angle  given  by  the  head  terminator  and 
the  end  point  of  the  drag.  The  extent  of  the 
arc  is  constrained  to  be  a  multiple  of  45 
deg. 

Arc  Block  2  The  same  as  Arc  Block  1  but  with  a  radius  of 
foxir  grid  divisions. 

The  four  tools,  Cross  Block,  Join  Block,  Switch  Block  1,  and 
Switch  Block  2,  create  iconic  blocks,  blocks  that  have  a 
fixed  size  and  shape.  They  are  created  by  simply  clicking 
the  mouse,  whose  cursor  takes  the  form  of  the  icon  for  the 
current  tool.  Along  the  outer  circle  of  such  a  cursor  are 
enlarged  points  called  hot  spots  at  which  connections  with 
other  blocks  can  be  made.  When  a  connection  is  established, 
the  newly  created  iconic  block  is  constrained  so  that  the 
slope  at  the  connecting  hot  spot  cind  the  slope  at  the  exist¬ 
ing  terminator  agree,  tsed  does  not  establish  more  than  one 
connection  when  an  iconic  block  is  created. 

Cross  Block  Create  a  cross  block. 

Join  Block  Create  a  join  block. 

Switch  Block  1  Create  a  switch  block  whose  turn  head  is  45 
deg  counter  clockwise  from  its  straight  head. 

Switch  Block  2  Create  a  switch  block  whose  turn  head  is  45 
deg  clockwise  from  its  straight  head. 

Train  Create  a  train.  The  drag  operation  for 

creating  a  train  begins  at  the  position 
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desired  for  the  head  end  of  a  train,  contin¬ 
ues  along  the  blocks  to  be  occupied  by  that 
train,  amd  stops  at  the  position  desired  for 
that  train’s  tail  end.  The  head  end  of  a 
train  is  indicated  by  am  angle  bracket,  and 
the  tail  end  is  indicated  by  a  square 
bracket.  All  blocks  that  are  occupied  by  a 
train  are  highlighted.  The  head  end  of  a 
train  is  constrained  to  start  in  a  regular  or 
station  block. 

Rotate  Rotate  an  iconic  block  clockwise  about  its 

center  to  the  next  hot  spot. 


Pulldown  Menus 

The  pulldown  menus  File  and  Customize  lie  in  a  menu  bar 
along  the  top  of  the  canvas  window.  They  contain  commands 
which  you  execute  by  pulling  down  the  menu  and  releasing  the 
mouse  button  on  the  command. 


The  File  menu  contains  the  following  commands  to  operate  on 
files ; 
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Open 


Save 


Save  As  . . . 


Clear  the  current  layout  and  create  a  new 
empty  layout,  requesting  a  layout  name  from 
the  user. 

Open  an  existing  layout  using  a  layout  data 
file  typed  by  the  user.  The  search  is  the 
same  as  specified  above. 

Save  the  current  layout  under  the  current 
file  name,  if  one  exists.  If  one  does  not, 
then  it  is  the  seune  as  executing  Save  As 

Save  the  current  layout  under  a  new  name 
specified  by  the  user. 


Close 


Close  the  current  layout  and  clear  the  can- 
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vas . 

Quit  Exit  the  application  after  first  checking  for 

any  unsaved  changes. 

The  Customize  menu  contains  the  following  commands  to  alter 

the  appearaince  of  the  current  layout  and  the  attributes  of 

the  blocks  contained  within: 

Change  Block  Attributes 

Change  the  attributes  of  a  selected  block 
(See  Select  above).  If  no  block  is  selected, 
a  warning  beep  is  sounded. 

Change  Default  Block  Attributes 

Change  the  default  creation  attributes  of  a 
block  type.  This  is  a  hiereo’chical  menu 
whose  submenu  are  the  various  block  types. 

Labels  Change  the  appearance  of  the  labels  on  the 

current  layout.  This  is  a  hierarchical  menu 
whose  submenu  entries  are:  Hames  —  Labels 
are  block  names;  Speeds  —  Labels  indicate 
the  minimum,  maximum,  and  stop  velocities 
associated  with  each  block;  Hide  Labels  — 
Hide  the  labels  in  the  current  layout. 

Hide/Show  Grid  Hide  (Show)  the  grid  lines  in  the  canvas  win¬ 
dow.  Note  that  this  does  not  turn  the  grid 
alignment  and  constraints  off,  it  merely 
removes  the  grid  from  view. 


Files 

tsroot/lib/tsed.uid 
See  Also 

ts(l),  layout  data  file  description 


Bugs  /  Restrictions 
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Due  to  a  bug  in  the  DEC  Xqdsg  server,  tsed  causes  the  X 
server  to  crash  when  using  the  Arc  Block  1  and  Arc  Block  2 
tools  with  X  servers  from  Ultrix  4.0  and  Ultrix  4.1.  There 
is  no  problem  in  Ultrix  4.2  and  the  Ultrix  4.2  X  server  can 
be  used  with  Ultrix  4.0  and  4.1. 
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tsim  -  Trainset  railroad  simulation 
Syntax 

tsim  [  flags . . .  ] 

Description 

tsim  simulates  a  Trainset  railroad.  The  Trainset  software 
consists  of  this  simulator,  an  interactive  graphics  editor 
tsed(l)  for  defining  railroad  layouts  and  graphics  monitor 
programs  tspanel(l)  and  tsviewCl)  for  displaying  the  state 
of  the  lailroad  and  manually  controlling  it.  See  The  Train- 
set  Railroad  Simulation  for  more  information. 

The  programs  tsim,  tspanel  and  tsview  are  ordineirily  invoked 
using  the  launch  program  ts(l). 

Interfaces 

tsim  provides  three  interfaces .  The  control  program  inter¬ 
face  (CPI)  is  used  by  computer  programs  that  control  a 
Trainset  railroad.  The  CPI  is  fully  documented  and  enables 
researchers  and  students  to  write  control  programs  for 
investigating  issues  such  as  real-time  computing  and  fault- 
tolerance.  Programs  such  as  acitest(l)  that  illustrate  the 
CPI  are  included  in  the  software  distribution. 

The  other  two  interfaces  are  used  internally  by  Trainset . 
They  are:  the  layout  interface,  for  reading  files  that 
describe  a  railroad  and  its  initial  state,  as  produced  by 
tsed;  and  the  monitor  interface,  for  communication  between 
tsim,  tspanel  and  tsview. 

Options 

-layout  layoutfile 

The  railroad  layout  to  be  simulated  is  described  in  the 
layout  data  file  layoutfile,  which  must  be  in  the  for- 
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mat  produced  by  tsed.  Specify  a  complete  absolute  or 
relative  path  for  layoutfile. 

-quorum  n 

Sets  the  voting  quorum  value  for  this  simulation  to  n. 
-simnum  number 

Number  determines  which  well-known  ports  are  to  be  used 
when  other  programs  are  initializing  communication  with 
this  simulation.  Permissible  values  for  number  are 
installation-dependent  and  typically  include  the  range 
0  to  100.  Multiple  instances  of  tsim  may  be  run  simul¬ 
taneously  on  the  same  host  if  they  use  different  values 
for  number. 

-update  seconds 

Specifies  the  frequency  that  tsim  is  to  send  state 
update  reports  to  graphics  monitor  programs .  Seconds 
may  be  a  decimal  value,  e.g.,  0.5. 

-window  seconds 

Sets  the  voting  window  value  for  this  simulation  to 
seconds . 

See  Also 

ts(l),  tsed(l),  tspanel(l),  tsview(l),  acitest(l). 
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tspanel,  tsview  -  Trainaet  railroad  monitor  programs 
Syntax 

tspemel  [  -simhost  hostname  ]  [  -simnum  number  ]  [  -tsroot 
dir  3 

tsview  C  -simhost  hostname  ]  C  -simnum  number  ]  [  -tsroot 
dir  ] 

Description 

tspanel  is  a  graphical  interface  for  manually  controlling 
and  displaying  quantitative  state  information  about  a  simu¬ 
lation  of  a  Trainset  railroad,  tsvies  displays  the  state  of 
a  Traimiet  railroad,  including  location  of  trains  and  set¬ 
tings  of  ssitches.  These  programs  enable  a  user  to  estab¬ 
lish  initial  conditions  of  train  motion  and  switch  settings 
in  a  railroad  and  to  monitor  the  progress  of  a  simulation. 
Each  program  receives  regular  reports  of  the  railroad 
layout’s  state  from  the  Trainset  simulator,  tsim(l).  See 
The  Trainset  Railroad  Simulation  for  more  information. 

tspanel  and  tsview  are  ordinarily  invoked  using  the  launch 
program  ts(l) . 

Options 

-simhost  hostname 

Specifies  the  host  that  is  running  the  simulator  tsim. 
-simnum  number 

number  determines  which  invocation  of  the  tsim  simula¬ 
tor  (at  the  indicated  host)  is  to  be  used.  The  monitor 
progr2uns  and  the  desired  invocation  of  tsim  should  use 
the  same  value  for  number. 

-tsroot  dir 

(DECwindows  implementation  only.)  Specifies  directory 
for  locating  uid  startup  file,  e.g.,  tsroot/tsview.uid 
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or  tsroot/lib/tsvieH.uid. 
Limitations 

Currently  implemented  on  DECwindoss  only. 

See  Also 

ts(l),  tsim(l). 
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